Build a Next.js app with Claude Code: scaffold to paid, deployed SaaS

You can build a full Next.js app with Claude Code by giving it a written spec, letting it plan in plan mode, and shipping one slice at a time: scaffold, database and auth, payments, tests, deploy. This hands-on guide walks through each step with the commands and prompts to use, and the checks that keep agent-written code safe to ship.

Can you build a Next.js app with Claude Code?

Yes: Claude Code can write almost all of a production Next.js app, as long as you supply the decisions, the accounts and the review. The reliable way to build a Next.js app with Claude Code is a loop: spec, plan, implement one slice, verify, commit, repeat.

Here is the path this guide follows, building a small paid SaaS (a feedback board where teams collect feature requests):

If you have never used Claude Code, start with our Claude Code tutorial for installation and permissions, then come back.

What do you need before you start?

You need Node.js 20.9 or newer, Claude Code signed in, a GitHub account, and test-mode accounts for your database, auth and payment providers. The Next.js installation docs list Node 20.9 as the minimum.

Set these up first so the agent never stalls waiting for a key:

• A GitHub repository for the project.
• A Postgres database (a hosted provider or local Docker).
• An auth approach: an established library or a hosted auth provider. Do not let the agent invent password handling.
• A Stripe account in test mode and the Stripe CLI for local webhooks.
• A Vercel account (or another host) for deployment.

Pick popular, well-documented libraries. Agents write noticeably better code for tools with many public examples, and you will find answers faster when something breaks.

Step 1: Scaffold the app and set up agent instructions

Scaffold with create-next-app, then make sure Claude Code reads the project's AGENTS.md. New Next.js projects ship with instructions that point agents to documentation matching your installed version.

npx create-next-app@latest feedback-board --yescd feedback-boardgit init && git add -A && git commit -m "Scaffold Next.js app"claude

The --yes flag uses the defaults: TypeScript, Tailwind CSS, ESLint, App Router, Turbopack, the @/* import alias, and an AGENTS.md file. According to the Next.js AI agents guide, Next.js 16.2 and later bundle version-matched docs in node_modules/next/dist/docs/, and the managed block in AGENTS.md tells agents to read the relevant guide there before writing code. This matters because a model's training data may describe an older Next.js.

Now the gotcha. Per the Claude Code memory docs, Claude Code reads AGENTS.md only when there is no CLAUDE.md. If you add a CLAUDE.md for your own rules, import AGENTS.md at the top so the Next.js instructions keep loading:

@AGENTS.md## ProjectFeedback board SaaS. Teams create boards, members post and vote on requests.## Commands- Dev: npm run dev- Lint: npm run lint- Test: npm test- E2E: npx playwright test- Build: npm run build (must pass before you say a task is done)## Rules- Server Components by default; "use client" only when needed- All data access goes through lib/db; check the user's team on every query- Never commit .env files; list new variables in .env.example

Next, give the agent eyes on the running app. Next.js 16 and later expose an MCP endpoint at /_next/mcp on the dev server, and the next-devtools-mcp package connects agents to it for errors, routes, logs and compilation status, per the Next.js MCP guide:

claude mcp add next-devtools -- npx -y next-devtools-mcp@latest

Choose a permission mode before the real work starts. acceptEdits lets the agent edit files and run common filesystem commands without asking, while still prompting for other shell commands; that is a comfortable middle ground for a new project on your own machine. Keep anything that touches production, such as deploy commands or database URLs for live data, behind a prompt.

With npm run dev running, Claude Code can check whether pages compile and what errors the browser hit, instead of guessing. For more on writing instruction files, see CLAUDE.md best practices.

Step 2: Write a spec and plan each feature

Put the product in a short spec file, then run every feature through plan mode before code is written. Plans are cheap to fix; implementations are not.

Create docs/spec.md with the essentials. Half a page is enough:

## Users and teams- Sign up with email or Google. A user belongs to one or more teams.- Team owner invites members by email.## Boards- A team has boards. Members post requests (title, description).- Members vote once per request. Sort by votes or newest.## Plans- Free: 1 board. Pro ($12/month): unlimited boards.- Stripe Checkout for upgrades, customer portal for billing changes.## Out of scope for v1- Comments, public boards, custom domains.

Then press Shift+Tab until Claude Code is in plan mode and ask for a plan, one slice at a time:

Read docs/spec.md and AGENTS.md. Plan the first slice only: sign-up,sign-in, teams and protected routes. List the files you will create,the database tables and columns, the libraries you want to add and why,and how you will test it. Do not write code yet. Ask me about anythingthe spec leaves open.

Let the agent propose libraries, but make the final call yourself. Ask it to compare two options for auth or the ORM in a short table (maturity, docs, how it fits the App Router, lock-in) and pick the boring, popular one unless there is a clear reason not to. Write the choice into CLAUDE.md so later sessions do not reopen it.

Read the plan carefully. This is where you catch a wrong library, a missing team check, or a schema that will hurt later. Approve it, and let the agent implement.

Step 3: Add the database and authentication

Build data and auth as one vertical slice, and verify authorization yourself. Most serious bugs in AI-built SaaS apps are users seeing data from another team.

After the agent implements the plan, ask it to prove the slice works:

Run the migrations against the local database, start the dev server,and verify: a new user can sign up, create a team and see an emptydashboard; a signed-out user is redirected from /dashboard; a user inteam A gets a 404 for a board ID from team B. Write tests for thesethree cases. Run lint, tests and npm run build. Show me the results.

Then review the diff yourself, focusing on:

• Every query that reads boards or requests filters by the current user's team.
• Server Actions and route handlers check the session; hiding a button is not authorization.
• No secrets in client components; only variables prefixed NEXT_PUBLIC_ reach the browser, and those must be safe to expose.
• .env.local is in .gitignore, and .env.example lists every variable without values.

Look at the migration files too. Agents sometimes add columns without indexes, use loose types for money or status fields, or create a second table for something that already exists. Ask for a short summary of every table and relation, and compare it with the spec before you build on top of it.

Commit when it passes. Small commits give you clean rollback points if a later slice goes wrong.

Step 4: Add Stripe payments

Use Stripe Checkout for upgrades and a webhook to update the user's plan; never trust the redirect alone. The webhook is the source of truth for whether someone paid.

Create the product and price in the Stripe dashboard (test mode) first, put the price ID and keys in .env.local, then plan the slice:

Plan the payments slice from docs/spec.md. Use Stripe Checkout for thePro upgrade and the Stripe customer portal for billing changes. Storethe Stripe customer ID and subscription status on the team. Update theplan only from a webhook route that verifies the Stripe signature.Handle checkout completion, subscription updates and cancellations, andmake the handler idempotent. Enforce the 1-board limit on the server.

To test webhooks locally, forward events with the Stripe CLI, as described in Stripe's webhook docs:

stripe listen --forward-to localhost:3000/api/webhooks/stripe

The command prints a signing secret (whsec_...) for your local .env.local. Complete a test checkout with a Stripe test card and confirm the team's plan changes only after the webhook arrives.

Step 5: Test and verify the whole app

Ask for end-to-end tests of the paths that make or lose money, and make lint, tests and a production build the agent's definition of done.

A good prompt for this stage:

Add Playwright tests for: sign up and create a team, create a board andpost a request, vote once (second vote is rejected), hit the free boardlimit, and upgrade through Stripe Checkout in test mode. Run them, fixfailures in the app code (not by weakening tests), then run lint andnpm run build.

Watch for tests that pass because they assert nothing useful. Our guides on writing unit tests with AI and AI test automation with Playwright cover how to spot weak tests and flaky ones.

You can also make verification automatic. A Claude Code hook that runs the linter after edits, or a rule in CLAUDE.md that npm run build must pass, stops the agent from declaring victory early.

Step 6: Deploy to Vercel

Connect the GitHub repository to Vercel (or deploy with the Vercel CLI), set production environment variables, and register a production Stripe webhook.

1. Ask Claude Code to list every environment variable the app needs and where each comes from.
2. Import the repository in Vercel, or install the CLI with npm i -g vercel and run vercel in the project, per the Vercel CLI docs.
3. Add production values for the database URL, auth secrets and Stripe keys in the project settings.
4. Run database migrations against the production database.
5. In Stripe, add a webhook endpoint for your production URL and copy its signing secret into Vercel.
6. Do one real checkout in test mode on the deployed app before switching Stripe to live keys.

Once the repository is connected, Vercel builds a preview deployment for each pull request. That fits the agent workflow well: let Claude Code open a pull request per slice, click the preview link, and test the change on a real URL before you merge.

Keep production credentials out of the agent's reach. The agent can prepare the deploy; you paste the secrets.

Common mistakes when building with Claude Code

The expensive mistakes come from skipping plans, big unreviewed diffs, and trusting the agent on security.

Our longer list of AI coding mistakes covers more of these patterns.

Your Next.js build checklist

Work through this list in order, and commit after every line.

• Scaffold with create-next-app, commit, and confirm AGENTS.md exists.
• Add CLAUDE.md with @AGENTS.md, your commands and your rules.
• Connect next-devtools-mcp so the agent can see the running app.
• Write docs/spec.md with scope, plans and what is out of scope.
• Build auth and teams through plan mode, then check authorization by hand.
• Add Stripe with a verified, idempotent webhook and test it with stripe listen.
• Add end-to-end tests for money paths and make npm run build part of done.
• Deploy, set secrets yourself, and run one test checkout in production.

Long builds like this one run better on a machine that stays on. Orkio has a Web/SaaS (Next.js) kit that sets up a ready project on an always-on box, where Claude Code keeps working after you close your laptop and opens pull requests you review from your phone.

Frequently asked questions