Skip to main content

Cloud and deployment · Beginner · 14 min

How to Deploy a Next.js 16 App to Vercel

By Padding · Updated 15 Nov 2026
Next.js 16 · Vercel

You will create a Next.js 16 app, deploy it to Vercel from Git (or from the command line), add an environment variable the safe way, and delete the project when you are done.

On this page

Vercel is a hosting platform made by the team behind Next.js. You connect a Git repository, and every push builds and deploys your app to a public URL, with no server for you to manage. That is the fastest way to put a Next.js app on the internet, and the trade-off is that you rent a platform, with its pricing and its limits, instead of running your own machine.

In this tutorial you will create a new Next.js 16 app, deploy it by importing a GitHub repository, repeat the deploy from the command line, and add an environment variable. At the end you will remove what you created, so nothing keeps running or billing.

Step 1 · Create the app

Create a new project with the official starter. The --yes flag accepts the recommended defaults (TypeScript, Tailwind CSS, ESLint, the App Router and Turbopack), so it asks no questions:

Bash
npx create-next-app@latest my-site --yes
cd my-site

The command creates the folder my-site, installs the dependencies and writes the starter pages in app/. Start it and open http://localhost:3000 in your browser:

Bash
npm run dev

Stop the server with Ctrl+C. Before you deploy, make sure the production build works on your own machine. Most failed deploys fail at this same step, and it is quicker to see the error locally:

Bash
npm run build

The build ends with a table of routes. If it prints errors instead, fix them first. Next.js 16 no longer runs the linter during next build, so run npm run lint yourself if you want to catch lint errors.

Step 2 · Put the code on GitHub

Vercel deploys from a Git repository. Check whether the starter already made one, and commit:

Bash
git status
git add -A
git commit -m "Initial commit" || true

If git status says not a git repository, run git init -b main first. Create an empty repository on GitHub, without a README, and push to it. With the GitHub CLI, one command does both, and --private keeps the repository private:

Bash
gh repo create my-site --private --source=. --push

create-next-app writes a .gitignore that already excludes node_modules, .next and your .env* files. Keep it that way: environment files with secrets do not belong in the repository (see /tutorials/keep-secrets-out-of-git).

Step 3 · Deploy from the dashboard

Sign in at vercel.com. Look for something like Add New, then Project, and pick your GitHub account and the my-site repository to import. The first time, GitHub asks you to allow the Vercel app access to your repositories; you can grant it to only the one you need. Vercel detects the Next.js framework and fills in the build settings, so leave them alone. Start the deploy.

The deployment page streams the build log. A minute or two later it shows a URL ending in .vercel.app. Open it: your starter page is live over HTTPS, with a certificate that Vercel manages.

From now on:

  • A push to your production branch (main) deploys to the production URL.
  • A push to any other branch, or a pull request, gets its own preview URL, which is how you review a change before it goes live.
  • Each deployment is kept, so you can promote or roll back to an earlier one from the project's Deployments list.

Check it worked

Make a visible change that cannot miss: add a new page, push it and watch a second deployment build. The commands assume the app lives in app/; if your project uses src/app, put it in src/app/hello/ instead.

Bash
mkdir -p app/hello
printf 'export default function Page() {\n  return <h1>Deployed from Git</h1>\n}\n' > app/hello/page.tsx
git add app/hello/page.tsx
git commit -m "Add a hello page"
git push

When the new deployment is ready, https://<your-production-address>/hello shows Deployed from Git. The new page also appears in the route table of npm run build.

Troubleshooting

  • The build fails on Vercel but passes on your machine: open the failed deployment's build log and read the first error. Common causes are a Node.js version difference (compare the version in the project's settings with node -v), an environment variable that exists only in your local .env.local, and a file name with different capitalisation. Your Mac may ignore case in file names, while the build machine does not.
  • The page loads but shows a 404 or an empty site: the project's root directory is wrong. If the app is in a subfolder of the repository, set the root directory in the project settings.
  • Vercel cannot see the repository: the GitHub app was not granted access to it. Change the app's repository access in your GitHub settings.

Step 4 · Deploy from the command line

You do not need Git integration to deploy; the CLI uploads the folder directly. This is useful for a quick test or from a script. Install the CLI, sign in, and deploy:

Bash
npm install --global vercel
vercel login
vercel

vercel with no arguments runs vercel deploy. In a folder that is not yet linked to a project, it asks a few questions, such as the scope (your account or team) and the project name, and then creates a .vercel folder that links the folder to the project. If that folder is already linked to the project from the dashboard, it deploys straight to it. The command prints the deployment URL. A deploy that is not marked as production is a preview. The first deployment of a brand-new project is always a production deployment; after that, add --prod:

Bash
vercel --prod

--yes skips the setup questions and accepts the defaults, which is what you want in scripts. Add .vercel to your .gitignore if the starter did not: it is local linking data. Since vercel login opens a browser, a script or CI job should use a Vercel access token in an environment variable (VERCEL_TOKEN) instead, created in your account settings and stored as a CI secret.

Step 5 · Add an environment variable

Configuration such as an API key belongs in environment variables on Vercel, not in the repository. Add one for the production environment with the CLI. It prompts for the value, so the value never lands in your shell history:

Bash
vercel env add API_KEY --environment production

Pick or confirm the environment when it asks. Production and Preview variables are stored as Secret by default, which means the value cannot be read back from the dashboard afterwards. Variables take effect on new deployments only, so redeploy (vercel --prod, or push a commit) after you change one. To use the same variables in local development, pull the development values into .env.local:

Bash
vercel env pull .env.local

In your code, read process.env.API_KEY in server code, such as a Route Handler or a Server Component. A variable whose name starts with NEXT_PUBLIC_ is written into the JavaScript that every visitor downloads, so never put a secret in one.

Step 6 · Add your own domain

The .vercel.app address is fine for testing. For a real site, add a domain in the project's settings, under something like Domains. Vercel then shows the DNS records to create at your registrar: for a subdomain such as www.example.com, a CNAME record, and for the bare domain an A record, or you can move the domain's nameservers to Vercel. Copy the values Vercel shows, since they can differ per project. The record types are explained in /tutorials/dns-records-explained-a-cname-mx-txt. DNS changes can take from minutes to a few hours to spread, and Vercel issues the HTTPS certificate once the records are visible.

Step 7 · Costs, and how to delete everything

Check the current terms at vercel.com/pricing before you rely on any plan. As a rule, the Hobby plan is free but is meant for personal, non-commercial projects with usage limits, and a commercial site belongs on a paid plan. Costs can grow with traffic, build minutes and some add-on features, so look at the usage and spend settings of your account.

To remove the project, with all its deployments and its production URL, delete it. This cannot be undone. The CLI shows the team and asks you to type the project name to confirm:

Bash
vercel project delete my-site

The GitHub repository stays. To delete it as well, give the GitHub CLI permission to delete repositories first, since its default sign-in does not include it, and then delete (this also cannot be undone):

Bash
gh auth refresh -s delete_repo
gh repo delete my-site

Also remove the .vercel folder in your local copy. If you added a domain, remove its DNS records at your registrar.

Next steps

  • Understand DNS before you add a domain: /tutorials/dns-records-explained-a-cname-mx-txt.
  • Keep tokens and keys out of Git: /tutorials/keep-secrets-out-of-git.
  • Self-host the same app instead: /tutorials/nginx-reverse-proxy-for-a-node-app.
  • Official references: nextjs.org/docs/app/getting-started/installation and vercel.com/docs/cli/deploy.

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.