Deploy Next.js to Vercel: Beginner Tutorial

Deploying a Next.js website to Vercel can be straightforward, but a successful deployment involves more than clicking a button. You need to connect your source code, confirm the build settings, configure environment variables, and verify the live site. This tutorial walks through those steps and explains how previews, custom domains, deployment logs, and plan limits fit into the process.

Key takeaways

Connect a Git repository to Vercel to deploy automatically when you push changes.
Check the framework, root directory, build command, and environment variables before the first production deployment.
Use preview deployments to review changes before they reach your production domain.
Treat environment variables prefixed with NEXT_PUBLIC_ as public; do not put secrets in them.
Check Vercel's current plan terms before choosing a plan, especially for commercial use or higher usage needs.

Before you deploy

You will need a Next.js project in a Git repository hosted by a provider that Vercel supports. Make sure the project runs locally and that its build succeeds. From the project directory, use the command for your package manager:

npm run build

If your project uses another package manager, run its equivalent build command, such as pnpm build or yarn build. Resolve build errors locally when possible; a successful local build does not guarantee that production has identical environment variables, but it is a useful first check.

Your project should have a build script in package.json, commonly:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

Keep the lockfile for your package manager in the repository. It helps the deployment environment install the intended dependency versions. If your project is inside a monorepo, identify the directory that contains the Next.js app before importing it.

Connect your Git repository

Sign in to Vercel and create a new project.
Choose the option to import a Git repository and authorize access if prompted.
Select the repository that contains your Next.js app.
Confirm the project settings, especially the root directory if the app is not at the repository root.
Add any required environment variables, then start the deployment.

Vercel generally detects Next.js projects and selects suitable framework defaults. After connecting Git, pushes to the configured production branch can create production deployments. Other branches and pull requests can produce preview deployments, depending on your project and integration settings. A preview deployment gives you a separate URL to review a change without replacing the production deployment.

Keep changes small and use pull requests where that fits your team’s workflow. Review the preview URL and deployment status before merging changes into the production branch.

Check the build settings

Open the project’s settings and review its build and development configuration. For a typical Next.js project, the build command is next build or the equivalent package script, such as npm run build. Vercel normally handles the output for a Next.js build, so you generally should not set a custom output directory such as .next unless you have a specific configuration that calls for it.

Check these items if your project does not build as expected:

Framework preset: Confirm that the project is identified as Next.js.
Root directory: In a monorepo, point to the directory containing the app’s package.json and Next.js files.
Install and build commands: Use commands that match your package manager and scripts.
Node.js version: If the project requires a particular version, configure a compatible version in the project and deployment settings.
Build output: Avoid overriding framework defaults without a reason. Static export and other custom output modes have different requirements from a standard Next.js deployment.

Settings changes usually affect future deployments. If you change a build setting and the existing deployment still reflects the old configuration, create a new deployment and inspect its build log.

Configure environment variables

A local .env.local file is not automatically a safe way to provide production configuration. Add the values your deployed app needs in the project’s environment variable settings, and select the environments where each value should be available. Common scopes include production, preview, and development; the available controls can depend on your project and plan.

For example, a server-side database connection string might be stored as an environment variable named DATABASE_URL. Do not commit secret values to Git or paste them into client-side code. In Next.js, variables prefixed with NEXT_PUBLIC_ can be exposed to browser code and should not contain secrets.

After changing an environment variable, deploy again so the new deployment can use the updated configuration. When debugging, confirm that the variable name is spelled correctly and that it is assigned to the environment you are testing. Avoid printing secret values in logs.

Deploy and read the deployment logs

Start the deployment from the project setup flow or trigger one with a push to the connected repository. Open the deployment details in Vercel to follow its build status and inspect logs if it fails.

A useful troubleshooting sequence is:

Find the first error in the build log rather than focusing only on the final failure message.
Check whether the error is an installation, compilation, type-checking, or configuration problem.
Confirm that required environment variables exist in the deployment’s environment.
Reproduce the build locally with the same package manager and, where possible, a compatible Node.js version.
Make a fix, push it, and review the new deployment rather than assuming an older deployment has changed.

Build logs cover the deployment build. Runtime or function logs may help diagnose problems that occur after the site is deployed, such as errors while handling a request. The exact log views and available retention or observability features can vary by plan, so check the current Vercel documentation and plan details when you need a particular capability.

Add a custom domain

A successful deployment gets a Vercel-provided URL. To use your own domain, add it to the project’s domain settings and follow the DNS instructions Vercel gives for that domain. DNS records depend on your domain and configuration, so use the values shown for your project rather than copying records from an unrelated setup.

After making DNS changes:

Allow time for the records to become visible across DNS resolvers.
Check the domain status in the project settings and correct any reported mismatch.
Test both the intended hostname and any redirect between www and the apex domain, if you use both.
Verify that HTTPS works before sharing the domain.

Do not remove existing DNS records without understanding what services they support. Email, verification, and other hosting services can rely on records unrelated to the website.

Verify the production deployment

A deployment marked successful is a useful signal, but verify the site itself before treating it as ready. Open the production URL in a browser and check key pages and flows, including pages that rely on server-side data or external services.

Use this checklist:

Confirm the correct deployment is associated with the production domain.
Load important routes directly, not only by navigating from the home page.
Test forms, authentication, API-backed content, and other essential interactions.
Check images, fonts, and other assets for failed requests.
Review the browser console and deployment logs for errors.
Test on a mobile-sized viewport and with a hard refresh on a nested route.
Confirm that production settings and environment variables differ from preview settings only where intended.

For a production issue, compare the affected deployment with the last known-good one. Inspect its build and runtime logs, then roll back or redeploy according to your team’s release process.

Free plans and paid features

Vercel’s plan names, limits, and feature availability can change. The free Hobby plan is generally positioned for personal, non-commercial use; do not assume that it is appropriate for a commercial project just because an initial deployment is free. Paid plans, such as Pro, are intended for different usage and collaboration needs and may include higher limits or additional capabilities.

Before choosing a plan, review Vercel’s current pricing and terms for your use case. Pay particular attention to commercial-use eligibility, usage limits, team features, and any deployment or observability capabilities your project depends on. Do not rely on a past quota or feature comparison: check the current plan information in your account and official documentation.

Common mistakes to avoid

Forgetting production environment variables: A project can work locally but fail after deployment if required values are missing from the production environment.
Exposing secrets with NEXT_PUBLIC_: Treat every variable with this prefix as potentially visible to users.
Setting an unnecessary output directory: Next.js deployments typically use framework defaults; a custom directory can break deployment behavior.
Importing the wrong directory: This commonly affects monorepos where the app is in a subfolder.
Testing only the homepage: Direct navigation to nested routes and important user flows can reveal problems that a homepage check misses.
Assuming a preview is production: Check the deployment details and hostname before testing or sharing a link.
Expecting settings changes to repair old builds: New environment variable or build setting values generally need a new deployment to take effect.
Copying DNS records from a tutorial without checking: Follow the records Vercel displays for the domain you actually added.

Conclusion

To deploy a Next.js site to Vercel, connect the project’s Git repository, verify the build configuration, provide environment variables in the right deployment scopes, and inspect the resulting logs. Then add and verify a custom domain if needed, and test the production site’s routes and core functionality. For plan eligibility, limits, and features, consult Vercel’s current official plan information before relying on a particular capability.