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.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.
You can create a new project from the Vercel Dashboard by clicking on the Add New drop-down button.
Creating a new project from the Vercel Dashboard.
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.
To edit project settings, choose a project from the dashboard, then, select the Settings tab:
Selecting the Settings tab from the Project Overview page.
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 build and development settings and the root directory settings. Check out our Build Step documentation to learn more.
You can configure Environment Variables directly from Project Settings. Check out the Environment Variables documentation to learn more.
Learn more about the default Install Command (and how to use the Project Settings to define a custom one) in our Build Step documentation.
As with other project settings, the changes you make to this setting will only be applied starting from your next deployment.
Learn more about how to customize the Node.js version of your project on the Runtimes documentation.
You can add custom domains for each project. See the Domains documentation to learn more.
To edit your project’s Git settings, select the Git menu item from your project settings page.
Selecting the Git menu item from the project settings page.
If you have not connected Vercel with GitHub, GitLab, or Bitbucket yet, you can do so from here.
Selecting a Git Provider.
Next, find the Git repository by choosing the respective Git namespace from the dropdown and searching for the name of the Git repository. Then, click on the Connect button to connect your project to the Git repository.
Choosing a GitHub repository to connect to your project.
Once your project has been connected to a Git repository, you will see it from the settings.
Your project has been connected to the GitHub repository.
If you’d like to disconnect your project from a Git repository, click on the Disconnect button.
By default, Vercel will issue a new Deployment with Build (unless the Build Step is skipped) for every commit 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.
You can customize the behavior for your Git repositories by ignoring the build step. To do this, go to Settings > Git in your project and enter a command in the Ignored Build Step section. This command tells Vercel whether or not a new Build needs to be issued:
Specify the Ignored Build Step command.
For example, if you are using Turborepo, you can set the Ignored Build Step to npx turbo-ignore to 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. If you are using Nx, you can set the Ignored Build Step to npx nx-ignore <project-name>. See the nx-ignore docs to learn more.
While the Deployment is in the BUILDING state, the command you've entered in the Ignored Build Step section will be run. If the command exits with code 1, the Build will continue as usual. However, if the command exits with code 0, the Build is immediately aborted, and the Deployment state is set to CANCELED.
The command is executed within the Root Directory and can access all System Environment Variables.
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.
Selecting the Security menu item from the Project Settings page.
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.
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.
To delete a project, choose a project from the dashboard, then select the Settings tab:
Selecting the Settings tab from the Project Overview page.
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.
You can transfer projects between your Vercel accounts with zero downtime and no workflow interruptions in the following cases only:
- Your Hobby account to a Pro Team
- Between two different Pro Teams
- From a Team back to a Hobby account
After the transfer, Teams no longer need to redeploy projects that were deployed under a Hobby plan or a different Team. You must be an owner to transfer a Project away from that 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.
Transferred | Not Transferred |
|---|---|
Deployments, Domains, Aliases, and the Project's configuration are transferred from the original Project | Environment Variables defined in the env and build.env configurations of vercel.json will not be transferred. They must be migrated to Environment Variables in the Project Settings or configured again on the target Team after the transfer is complete |
Environment Variables are copied to the target Team. If an Environment Variable is associated to a Secret that exists on the target Team, that Secret will be renamed | Integrations associated with your Project will not be transferred. They must added again after the transfer is complete |
When transferring 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.
To begin transferring a Project, choose a project from the Vercel dashboard.
Selecting the project from the Vercel Dashboard.
Then, go to the project Settings tab from the top menu:
Selecting the Settings tab from the Project Overview page.
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.
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.
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.
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!
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.