What Is the Vercel App? Deploy a Next.js Project for Free

The Vercel app is not a separate store program you install on your desktop. It is Vercel itself: the service that takes your Next.js project, builds it and serves it at a vercel.app address. What the platform is for is covered in the What is Vercel post. Here I cover the order of steps for your first deployment.

Account and repository

Don't leave the code as a folder sitting on your computer. Put it in a repository on GitHub, GitLab or Bitbucket. The build command in package.json should work on your own machine. A project that fails locally will fail on Vercel too. If the framework is Next.js, Vercel detects it from the repository. If it doesn't, pick Next.js in the framework field.

The free Hobby plan is for experiments and personal sites. If you are going to launch client work or a company project, check the plan's commercial terms. The terms can change. The text on the screen is more current than the sentence in this post.

First deployment

Sign in with your Vercel account, import the repository and choose the production branch. In most projects this branch is main. If the root directory is the root of the repository, leave it as is. If the project lives in a subfolder, enter that folder in the root directory field. After you press the deploy button, watch the log. A successful run gives you a vercel.app address.

Every push to the same repository starts a new deployment. A separate preview address is generated for each pull request. A preview does not overwrite the production address. Make this a habit. Don't push half-finished work straight to the production branch.

Environment variables and Node

Keys are not written into the repository. In the Vercel project settings they live separately for Production, Preview and Development. A value that is in your local .env file does not exist on the server. If it is missing, the page seems to open but the data stays empty. After adding the value, redeploy. An old deployment does not pick up the new variable on its own.

If the Node version is newer locally, the build can fail. Specify the major version you use in the project in the engines field. If you don't, Vercel uses its own default.

When to use the CLI

If the repository is connected, the dashboard is enough. For a test outside the dashboard, the npx vercel command in the project folder goes to the same service. Don't mix the two paths. A project either flows from the repository or is uploaded by hand. If both happen, it gets confusing which version is live.

A custom domain is not required from day one. If the vercel.app address works, the deployment is done. You add the domain once the DNS record is ready. If the site doesn't open, look at the deployment log first, not the domain.

Preview versus production

When a pull request is opened, Vercel generates a second address. This address does not change the production site. Text, images and environment variables are checked there first. Preview variables and production variables sit in separate boxes. A key that works in preview may be empty in production. Fill in both.

Every push merged into the production branch is a new production deployment. The old address stays around for a while. Rolling back means promoting the previous deployment again. You don't have to revert the code by hand and create a second bug. The dashboard shows which deployment is live. Don't blame the domain without checking.

Monorepo and root directory

If the repository has more than one application, tell Vercel which folder is the site. If the root directory is left empty, it looks for the package.json at the root of the repository. If the site is under apps/web, the root directory must be that path. If the wrong folder is selected, the build fails with another package's error and the log is misleading.

Leave the build command relative to that folder too. A command that works at the root may look for missing dependencies in the subfolder. Going into that folder locally and running the same command saves the half hour you would lose in the dashboard.

The first line to look at in the log

The log is long. Scroll to the bottom. Module not found, Missing environment variable and a framework version mismatch are the three most common outcomes. In the first, the name or folder of the imported file is wrong. In the second, the variable name in the settings does not match the code. Upper and lower case count too. In the third, the local Next.js version and the lock file in the repository have drifted apart. Push the lock file.

Don't mistake warning lines for errors. If the build ended in red, there is an error. A run that ends with a yellow warning is usually live. Opening the address and clicking around the page is a more reliable test than reading the log from start to finish.