Vercel.com
Vercel.com is a cloud platform that automates your Javascript project's building, deploying, and scaling. Vercel can be set up to watch your GitHub repository, and every time you merge a pull request, it can trigger a new build process. When the build process is done, it will automatically deploy the code (depending on the branch, it will either deploy it as a staging or production version).
Vercel has a (free) Hobby plan for developers who want to start a side project or just experiment with the service. It includes 6000 minutes of build execution for Automatic CI/CD deployments, 100 GB of bandwidth usage, and more.
Create an account (sign up)
- visit vercel.com
- click on Sign Up in the top right
- select the Hobby plan
- then a field pops up, asking you for your name. Enter a name (you can use your full name, or as I did, use your GitHub username or any display name you like). If you already or later plan to work in a team, then I recommend you choose a name they will recognize)
Select a Git provider to import an existing project from a Git Repository
- next, they ask you to connect your Git provider (or use your email address by clicking on "Continue with Email") to create a new account; I intended to connect to a GitHub account, so I clicked on the GitHub button (or click on GitLab or Bitbucket if that is the git provider hosting your code), I usually try not to connect too many accounts which each other as a breach into one of them could potentially give the attacker access to the services that are linked to it too, but in this case, I chose to because in the next step, we need to connect our GitHub account anyway and allow Vercel to access repositories
- for a guide about creating a GitHub account, check out my chapter Create a GitHub account (sign up) in the GitHub post
- next, a pop-up window will open, asking you to authorize Vercel; there is one request they do, which is called Act on your behalf, this means that Vercel will be able to do tasks on your repositories, this is needed so that Vercel can fetch your code after you made a new commit or pull request and deploy the code on their servers (you will later get asked to give access to one or more repositories, meaning you can define which repositories Vercel can access and which not)
- click on Authorize Vercel, and you will get redirected to your new Vercel account dashboard
Add a new project
If you are NOT on the new project page yet, in the top left navigation, click on Overview
On the overview page, on the top right, click on Add New... and select Project
Manage git repository permission to allow Vercel to access it
The first step when creating a new Vercel project is Import Git Repository, but only repositories for which you have granted Vercel access will be listed
If you created a Vercel account using an email address and do NOT have a git provider app connected yet, then this is the first thing you need to do is follow the steps in the previous chapter to select a git provider (to import an existing repository)
If you have already connected to a git provider in the past (I will use GitHub as a provider in this example, you might have connected using another provider like Bitbucket or GitLab), then that provider will be selected by default, click on the down arrow if you want to add or switch to another provider
Now that the git provider is selected, you will see a list of repositories
If your repository is in the list, then you are done for this step and can jump to the next chapter to import a git repository
If your repository is NOT in the list of repositories because you have not granted Vercel permissions to access it, then you have 2 options:
I had trouble using option 1 recently, every time I clicked on the Adjust App Permissions Link, I would get a red modal box telling me that:
The popup to install the GitHub App could not be opened.
The workaround here is to use option 2
Option 1:
First, click on the Adjust GitHub App Permissions link to add access permissions for that repository
Next, click on the git provider button (in my case, the GitHub button) to start the process
Next, Vercel will open a modal asking you to give access to one or more repositories. I recommend only providing access to the repository where you store the code you want to deploy. To do so, click on the radio button next to Only select repositories, but if you prefer, you can also just allow access to all repositories
Now click on the Select repositories select box and select your git repository
Next, click on Install at the bottom of the modal
Option 2: Open the GitHub apps settings page at github.com/settings/installations
Then click on the Configure button (on the Vercel row)
Next, scroll down to the Repository access section, Only select repositories is selected, and below that is a Select repositories select box. Click the down arrow and then search for the new repository you want to add
Then click on the repository in the results
Now that it got added to the list of repositories Vercel will have access to, finally click on the save button to finalize the changes
You are now done on GitHub. Go back to Vercel.com. You should now be on the overview page (of your Vercel account), on the top right, click on Add New... and select Project
Import a git repository
Now that your repository is in the Git Repository list, the next step is to click on the Import button that is on the right of your repository name
Configure a Vercel Project
Now you will be on a new Configure Project page, you can change the Project Name of the project (I left it as is, as I like it to match the name of my repository)
Next, you can choose a Framework Preset, I selected Next.js, but of course, you select the framework (Astro, Remix, ...) that you are using in your project
The next option, Root Directory, you can leave it as is if your project is located in the root of your repository (even if your code is an ./src
folder, the actual root of the project would still be ./
), if you use a monorepo that hosts multiple projects, then you may want to set the Root Directory to the path of your project, for example ./packages/PROJECT_NAME
You can click on the Build and Output Settings to see what options are included, in this example, we don't need to touch the Build and Output Settings because we chose a Framework Preset earlier, meaning these values will already be set to defaults, if you know what you are doing and depending on what Framework you chose, you may want to adjust those values by using the override switch on the right and then entering your custom values
We have no use for the Environment Variables just yet. It is, however, an interesting feature that you will probably use at some time, as it lets you add environment variables to your project. Instead of having a .env file in your project, you set the key/value pairs using the Vercel interface, and Vercel will then pass those env variables to the javascript runtime. You can later download a copy of those env variables into your development environment if you want to have an actual file in your codebase
Finally, click on Deploy (unfortunately, the only way to save the imported project is to click Deploy, which will start a deployment. You may need more time to be ready to make your first deployment, and your main branch may still be empty. This doesn't matter; still, proceed and click Deploy. If the main branch is empty, the deployment will just fail, but your project will be saved. You can also click on Cancel Deployment if you want)
Sentry integration for Vercel
First, open the Sentry integration page on Vercel
On the bottom right, click on Add Integration
In the form, first, select your Vercel account
Chose the radio button Specific Projects and then select the project(s) for which you want to enable the sentry integration
Now, review the permissions you are giving to Sentry and click on **Install ** if you are okay with them.
This will open a Sentry.io modal to connect your projects. In the first select box, choose your project on Vercel, and in the second, select box your project on Sentry.io. Finally, click the + (plus sign) button to add a new connection.
Then click the Complete on Vercel button to return to Vercel. Now you are done, you can come back to the Sentry integration page on Vercel later and make some configuration adjustments or eventually remove the integration
If you want to verify that the environment variables have been set correctly by the Sentry Integration, go to your Vercel Overview page, click on the name of your project, then in the top project navigation click on Settings and then on the settings page in the left navigation click on Environment Variables, if you now scroll down a bit you should see that the integration has added an entry for SENTRY_AUTH_TOKEN and a few other SENTRY_XXX environment variables