12 min read

Projects Overview

To deploy on Vercel, you need to create a Project, which groups deployments and custom domains. Learn how to set up and configure projects with this guide.
Table of Contents

To deploy on Vercel, you need to create a Project. A Project groups deployments and custom domains. Each project can receive deployments from GitHub, GitLab, Bitbucket, or Vercel CLI.

To learn more about limits on the number of projects you can have, see Limits.

To create a new project:

  1. On the Vercel dashboard, ensure you have selected the correct team from the scope selector
  2. Click the Add New… drop-down button and select Project:
 Creating a new project from the Vercel dashboard.
Creating a new project from the Vercel dashboard.
  1. You can either import from an existing Git repository or use one of our templates

You can manage your project on Vercel in your project's dashboard. See our project dashboard docs to learn more.

In Project Settings, you can make changes about all areas relating to your project, including domains, log drains, integrations, Git, caching, environment variables, deployment protection, and security.

To edit project settings:

  1. Ensure you have selected your Team from the scope selector
  2. Choose a project from the dashboard
  3. Select the Settings tab
  4. Find the settings you need and make changes

Project names can only consist of up to 100 alphanumeric lowercase characters. Hyphens can be used between the name but never at the start or end.

You can edit settings regarding the build and development settings, root directory, and the install command. See the Configure a build documentation to learn more.

The changes you make to these settings will only be applied starting from your next deployment.

None of your existing deployments will be affected when you toggle this setting. If you’d like to make the source code or logs private on your existing deployments, the only option is to delete these deployments.

Learn more about how to customize the Node.js version of your project in the Runtimes documentation.

To locate your Project ID:

  1. Ensure you have selected your Team from the scope selector
  2. Choose your project from the dashboard
  3. Select the Settings tab
  4. Under General, scroll down until you find Project ID. The ID should start prj_
  5. Copy the Project ID to use as needed

Learn more about using Comments on preview deployments in the Comments docs.

You can configure Environment Variables directly from Project Settings. Check out the Environment Variables documentation to learn more.

You can add custom domains for each project. See the Domains documentation to learn more.

Once you have connected a Git repository, select the Git menu item to edit your project’s Git settings. These settings include specifying the production branch name, managing Git Large File Storage (LFS), creating Deploy Hooks, and ignoring the build step when a commit is pushed to the Git repository. from your project settings page.

To disconnect your Git repository from your Vercel project:

  1. Choose a project from the dashboard
  2. Select the Settings tab and then select the Git menu item
  3. Under Connected Git Repository, select the Disconnect button.

If you have LFS objects in your repository, you can enable or disable support for them from the project settings. When support is enabled, Vercel will pull the LFS objects that are used in your repository.

You must redeploy your project after turning Git LFS on.

By default, Vercel creates a new deployment and build (unless the Build Step is skipped) for every commit pushed to your connected Git repository.

Each commit in Git is assigned a unique hash value commonly referred to as SHA. If the SHA of the commit was already deployed in the past, no new Deployment is created. In that case, the last Deployment matching that SHA is returned instead.

To ignore the build step:

  1. Choose a project from the dashboard
  2. Select the Settings tab and then select the Git menu item
  3. In the Ignored Build Step section, select the behavior you would like. This behavior provides a command that outputs a code, which tells Vercel whether to issue a new build or not. The command is executed within the Root Directory and can access all System Environment Variables:
    • Automatic: Each commit will issue a new build
    • Only build production: When the VERCEL_ENV is production, a new build will be issued
    • Only build preview: When the VERCEL_ENV is preview, a new build will be issued
    • Only build if there are changes: A new build will be issued only when the Git diff contains changes
    • Only build if there are changes in a folder: A new build will be issued only when the Git diff contains changes in a folder that you specify
    • Only build Turborepo app if there are changes: automatically detect if your project or one of its dependencies has changed and needs to be built and deployed. See the turbo-ignore docs to learn more.
    • Don't build anything: A new build will never be issued
    • Run my Bash script: Run a Bash script from a location that you specify
    • Run my Node script: Run a Node script from a location that you specify
    • Custom: You can enter any other command here, for example, only building an Nx app (npx nx-ignore <project-name>)
  4. When your deployment enters the BUILDING state, the command you've entered in the Ignored Build Step section will be run. The command will always exit with either code 1 or 0:
    • If the command exits with code 1, the build continues as normal
    • If the command exits with code 0, the build is immediately aborted, and the deployment state is set to CANCELED

Canceled builds are counted as full deployments as they execute a build command in the build step. This means that any canceled builds initiated using the ignore build step will still count towards your deployment quota.

To learn about more advanced usage see the "How do I use the Ignored Build Step field on Vercel?" guide.

If you have set an ignore build step command or script, you can also skip the build step when redeploying your app:

  1. From the Vercel dashboard, select your project
  2. Select the Deployments tab and find your deployment
  3. Click the ellipses (...) and from the context menu, select Redeploy
  4. Uncheck the Use project's Ignore Build Step checkbox

Vercel supports deploy hooks, which are unique URLs that accept HTTP POST requests and trigger deployments. Check out our Deploy Hooks documentation to learn more.

Protect your project deployments with Vercel Authentication and Password Protection. See Deployment Protection to learn more.

Select the Security menu item from your project settings page to edit your project's security settings.

By default, the paths mentioned below can only be accessed by you and members of your Vercel Team. Turning off Logs and Source Protection will make them publicly accessible.

  • /_src: Displays the source code and build output.
  • /_logs: Displays the build logs.

This setting is overwritten when a Deployment is created using Vercel CLI with the --public option or the public property in vercel.json.

Do not edit this setting if you don’t want your source code or logs to be publicly accessible.

For Deployments created before July 9th, 2020 at 7:05 AM (UTC), only the Project Settings is considered for determining whether the Deployment's Logs and Source are publicly accessible or not. It doesn't matter if the --public flag was passed when creating those Deployments.

If you receive a pull request from a fork of your repository that includes a change to the vercel.json file or the Project has Environment Variables, ​Vercel will require authorization from you or a Team Member to deploy the pull request.

This behavior protects you from leaking sensitive Project information.

You can disable this protection in the Security section of your Project Settings.

Do not disable this setting until you review Environment Variables in your Project as well as vercel.json in your source code.

You can choose to temporarily pause a project to ensure that you do not incur usage from metered resources on your production deployment.

To pause your project when you reach your spend amount, select the Pause all production deployments in the Spend Management section of your team's settings. To pause a project manually or with a webhook you can use the REST API:

  1. Ensure you have access token scoped to your team to authenticate the API
  2. Create a webhook that calls the pause project endpoint:
    • You'll need to pass a path parameter of the Project ID and query string of Team ID:
    • Use your access token as the bearer token, to enable you to carry out actions through the API on behalf of your team
    • Ensure that your Content-Type header is set to application/json

When you pause your project, any users accessing your production deployment will see a 503 DEPLOYMENT_PAUSED error.

You can manually make a POST request to the pause project endpoint without using webhook.

Resuming a project can either be done through the REST API or your project settings:

  1. Go to your team's dashboard and select your project. When you select it, you should notice it has a paused icon in the scope selector
  2. Select the Settings tab
  3. You'll be presented with a banner notifying you that your project is paused and your production deployment is unavailable
  4. Select the Resume Service button
  5. In the dialog that appears, confirm that you want to resume service of your project's production deployment by selecting the Resume button

Your production deployment will resume service within a few minutes. You do not need to redeploy it.

Deleting your project will also delete the deployments and domains within it. If you have any deployments that are assigned to a custom domain and do not want them to be removed, make sure to deploy and assign them to the custom domain under a different project first.

To delete a project, choose a project from the dashboard, then select the Settings tab.

At the bottom of the General page, you’ll see the Delete Project section. Confirm that you'd like to delete the project and click the Delete button.

The Delete Project section.
The Delete Project section.

You can transfer projects between your Vercel accounts with zero downtime and no workflow interruptions.

Projects can be transferred between plans as long as the project owner is a member of both the source and destinations of the transfer. For example, a project can be transferred from a personal account (Hobby) to an Enterprise account, and vice versa.

You must be an owner of the team you're transferring from, and a member of the team you're transferring to. For example, you can transfer a project from your Hobby account to an Enterprise team account, and vice versa if you're an owner on the Enterprise team.

During the transfer, all of the project’s dependencies will be moved or copied over to the new Vercel Team namespace with absolutely no downtime.

To begin transferring a Project, choose a project from the Vercel dashboard.

Then, go to the project Settings tab from the top menu.

From the left sidebar, click General and scroll down to the bottom of the page, where you'll see the Transfer Project section. Click Transfer to begin the Transferring flow.

The Transfer Project section.
The Transfer Project section.

Select the Vercel account or team you wish to transfer the Project to. You can also choose to create a new Team.

Choosing an account to transfer the Project to.
Choosing an account to transfer the Project to.

If the target Vercel Team does not have a valid payment method, you must add one before transferring your Project to avoid any interruption in service. If a valid payment method is added to a Team on a Pro Trial Plan, the trial will be upgraded to the Pro Plan immediately.

This final step lists all the Project Domains, Aliases, and Secrets that will be transferred. You can also choose a new name for your Project. By default, the existing name is re-used. You must provide a new name if the target Vercel Account already has a project with the same name.

The original Project will be hidden when initiating the transfer, but you will not experience any downtime.

Reviewing the Project data that will be transferred to the target Vercel Account, and choosing a new Project name.
Reviewing the Project data that will be transferred to the target Vercel Account, and choosing a new Project name.

After reviewing, click Transfer to initiate the Project transfer.

You will be redirected to the newly created Project on the target Vercel Account with in-progress indicators.

When a transfer is in progress, you may not create new deployments, edit project settings or delete that project.

Transferring a Project may take between 10 seconds and 10 minutes, depending on the amount of associated data.

When the transfer completes, the transfer's initiator and the target Team's owners are notified by email. You can now use your Project as normal!

Once you transfer a project from a Hobby account to a Vercel team, you may choose to enable additional paid features on the target team to match the features of the origin account. These include:

Project Domains will automatically be transferred to the target team by delegating access to Domains.

For example, if your Project uses the Domain example.com, the Domain will be moved to the target team. The target team will be billed as the primary owner of the Domain if it was purchased through Vercel.

If your Project uses the Domain blog.example.com, the Domain blog.example.com will be delegated to the target team, but the root Domain example.com will remain on the origin Vercel scope. The origin Vercel scope will remain the primary owner of the Domain, and will be billed as usual if the Domain was purchased through Vercel.

If your Project uses a Wildcard Domain like *.example.com, the Wildcard Domain will be delegated to the target team, but the root Domain example.com will remain on the origin Vercel scope.

This only applies when transferring away from a Team.

When transferring between Teams, you may be asked whether you want to add additional features to the target Team to match the origin Team's features. This ensures an uninterrupted workflow and a consistent experience between Teams. Adding these features is optional.

Last updated on February 6, 2023