Prepare the Next.js project

A deployment platform can’t fix a build that is already broken. So before we touch Vercel, we make sure the project builds cleanly from what is in Git.

We’ll use the Field Notes app from the Next.js course. Any small Next.js repository you control works too.

Build it the way Vercel will

Vercel runs an install and a build. Run the same steps locally first:

npm install
npm run lint
npm run build
git status

Lint should exit with no errors. The build should print the route table, including /notes/[slug] and /api/health. And git status should be clean, or show only files you meant to change.

Commit everything to Git. Vercel can deploy from the CLI without a repository, but Git gives us reviews, history, and the release workflow this course is built on.

The clean-clone test

“It works on my machine” is weak evidence. The stronger test is a fresh clone in a temporary folder:

git clone [email protected]:flaviocopes/field-notes.git /tmp/field-notes-check
cd /tmp/field-notes-check
npm install
npm run build

This catches the things a warm working copy hides. Files you forgot to commit. A tool you installed globally. A missing lockfile. A path that works on macOS but fails on Linux because of case sensitivity. An environment variable that lives only in your shell.

Pin the Node.js version too, so the build machine matches your laptop. The engines field in package.json is the usual place:

{
  "engines": {
    "node": "22.x"
  }
}

Write down the environment

Make a short list of every environment variable the app reads. For each one write the name, what it’s for, and whether it’s needed at build time or at request time. Do not write the values. The values go in Vercel later, and never in Git.

Two more things help every deployment after this one. Add a health route at /api/health that returns 200 when the app starts, without touching credentials or running anything destructive. And pick one real user path for the post-deploy check. For Field Notes, that is creating a note and opening it.

Try this on your own project: clone the repository into a temporary folder and build it using only the committed files plus your documented environment values. If it fails, you found a problem before Vercel did.