Vercel is really convenient platform for hosting JavaScript oriented projects. It has a ton of features and great developer experience (DX) when it comes to building, deploying, and potentially scaling your website or app. But sometimes that great DX gets in the way because you’re not following the happy path.

For instance, say you wanted to deploy to Vercel without having to link your repository to their platform. Perhaps there are security concerns, you’re using a hosted Git provider that’s not supported, or maybe not even using Git. 😱 Or perhaps you’re running a monorepo and only want to deploy one application (of many) to Vercel without exposing the other applications. If you find yourself in any of these situations among others, Vercel’s happy path probably won’t work for you.

Luckily, there is a way around all of this! Vercel has a handy CLI that allows you to create a Vercel project (without linking a repository) and deploy your code to Vercel.

Installing the Vercel CLI

The first thing you’ll need to do is install the Vercel CLI. You can either do this globally or locally in your project. For the sake of this guide, we’ll approach things from the local standpoint.

Assuming you have Node.js and npm installed, run the following command in your project:

npm install -D vercel

Then you can run the following to make sure the CLI has been successfully installed:

npx vercel -v

This should print the version of the Vercel CLI that was installed. Great! We’ve installed the Vercel CLI, now we need to set up our Vercel project.

Creating a Vercel project

A Vercel project is necessary to deploy to Vercel. Normally, you’d create a project by logging into the Vercel web app and linking an existing hosted Git repository. The Vercel CLI allows you to create new projects without having to do that.

First, you’ll need to authenticate to Vercel using the CLI:

npx vercel login

This will prompt you to authenticate using a variety of methods:

? Log in to Vercel (Use arrow keys)
❯ Continue with GitHub
  Continue with GitLab
  Continue with Bitbucket
  Continue with Email
  Continue with SAML Single Sign-On
 ─────────────────────────────────
  Cancel

After you’ve successfully authenticated, you should see the something like the following message in your terminal:

? Log in to Vercel Continue with GitHub
> Success! GitHub authentication complete for hello@example.com
Congratulations! You are now logged in. In order to deploy something, run `vercel`.

Now, we can create our Vercel project with the CLI:

npx vercel

This will initiate a prompt to set up a Vercel project. Once you get to the step where it asks you if you want to link to an existing project, enter n for no. You will then be prompted to enter a name for your project and where your code is located (usually, this should be the root of your project).

The Vercel CLI will then analyze your project and auto-detect some project settings such as the build command and the output directory. You are free to update these settings as you see fit.

Once you’ve confirmed your project’s settings, the Vercel CLI will attempt to build and deploy your project to a preview URL. This is an opportunity to see if everything is working properly, but you can abort this process by pressing ctrl+c.

You’ll notice that a new directory has been added to your project at .vercel. This directory houses files necessary for the Vercel CLI to build and deploy your project. Take a look at .vercel/project.json to see which Vercel project is associated with your local project. You’ll also find any project settings you’ve customized here.

If you are tracking your project with Git, it may be appropriate to add the .vercel directory and its contents to your .gitignore so you don’t leak any details about your Vercel deployments.

Next up, we’ll go over how to build and deploy your project to Vercel.

Building and deploying to Vercel

Now that you have your Vercel project set up, you can now deploy with a simple command:

npx vercel deploy

This will build your project using your project’s build settings and deploy it to a preview URL on Vercel. A preview URL allows you to preview the result of your deploy without touching what is already at your production URL. This is a great way to stage your deployment for testing. The Vercel CLI will output the resulting preview URL:

🔍  Inspect: https://vercel.com/example-projects/my-example/abcdef [1s]
✅  Preview: https://example-abcdef-example-projects.vercel.app [1s]

To deploy to your production URL, run the same command with the --prod flag:

npx vercel deploy --prod

The Vercel CLI will output the resulting production URL:

🔍  Inspect: https://vercel.com/example-projects/example/abcdef [1s]
✅  Production: https://example-abcdef-exampe-projects.vercel.app [1s]

You’ll notice that when you use the vercel deploy command, you aren’t actually building the your project on your local machine. If you look at the logs for each deploy via the provided inspect URL, you’ll actually see that the builds occur on Vercel’s servers. This means that you’re actually uploading your project’s source files to Vercel on each deploy which may or may not be what you want. Let’s go over how to build locally and only send our built project to Vercel.

First, you’ll need to build your project using the Vercel CLI:

npx vercel build

This will build your project using the settings you specified earlier and place the built files in .vercel/output.

Now let’s deploy the built files to Vercel:

npx vercel deploy --prebuilt

The --prebuilt flag will signal to the Vercel CLI that you have already built the project locally and only want to deploy those files (and not your source files) to Vercel. The Vercel CLI will spit out a preview URL just like before.

Now let’s deploy to production. We can use the same commands, but with the --prod flag instead:

npx vercel build --prod
npx vercel deploy --prebuilt --prod

Awesome, we’ve now built our project locally and deployed those files to Vercel without having to expose our source code! Next, let’s go over how to integrate this deploy process more tightly in our project.

Creating a deploy command

So far, we’ve been using npx to run all of our deploys. This works, but we can actually make the process more streamlined for our project by rolling up the npx commands into a package.json script.

In our project’s package.json, we can define some new scripts:

"scripts": {
  "deploy": "vercel build --prod && vercel deploy --prebuilt --prod",
  "deploy:preview": "vercel build && vercel deploy --prebuilt"
}

Note how we’ve added two new scripts: deploy and deploy:preview. Running npm run deploy will do a production URL build and deploy while npm run deploy:preview will do a preview URL build and deploy.

Next steps

Today we went over how to install the Vercel CLI, set up a Vercel project (without linking a Git repository), deploy a project to Vercel, and build and deploy a project to Vercel without exposing our source code.

I use this workflow almost daily for generating preview URLs for prototypes or small projects that I can distribute to stakeholders without having to push the code up to a hosted Git provider like GitHub. It affords me more control over my source code and when deploys happen (at the cost of convenience).

To get even closer to the great DX and convenience that Vercel provides, you could integrate this deploy mechanism into a CI/CD process like GitHub actions. The Vercel CLI also offers a ton of other functionality, like the ability to inspect deploys, retrieve logs, and even rollback deploys! I’d highly recommend checking out the documentation to learn more.