Getting started with Vercel

What is Vercel?

Vercel is an online service that builds and deploys web apps and websites. It allows you to preview designs you are working on and changes you are making to the FreeSewing app and websites. By sharing links to your builds/deployments, other people can also preview your work.

Vercel offers a free “Hobby” account for personal, non-commercial use, so everyone is able to use it.

NOTE|

This tutorial assumes that you already have a GitHub account containing a fork of the FreeSewing repository.

Why you might want to use Vercel

There are reasons why you might want your own Vercel account:

  • You can preview your changes:
    • if you develop on a mobile device or if you do not have access to a computer.
    • without having to set up and maintain development environments on your own computer.
    • without having to manually rebuild your development environments each time there is a code change.
  • You can more easily share your work with others.

However, it is not necessary to have your own Vercel account. Because we use Vercel to preview pull requests, if you always submit your work to the main repository then you will be able to share your work without needing to use Vercel yourself.

About repositories, projects, and deployments

Vercel works through repositories, projects, and deployments.

Repositories are simply Git repositories, for example your personal fork of the FreeSewing repository. You will select the repositories you wish to import into Vercel.

Within each repository there can be multiple projects.

Projects are specific build types for the repository. For example, one project in your FreeSewing repository could be the one that builds the freesewing.org website. You would use this project to test new designs or changes to existing designs. Another project could be the one that builds the freesewing.dev website, used to test documentation changes on that website.

TIP|

Free Hobby accounts are limited to 3 Projects per Git repository.

Under each project there will be many, many deployments.

_Deployments are simply builds, an instance of a website/app built from a specific commit version of a specific branch of the repository. These deployments can be accessed using a web browser to preview the web app or website.

Vercel automatically builds a deployment for every push or update you make to every branch in your repository. The reason why Vercel builds these deployments automatically is so you will always have the latest version available to test without having to think about it or do any additional work. And, because deployments are built for every push and update, you have the ability to easily test different versions, past and current. This ability can help you identify what code change might have introduced an issue or change in behavior.

TIP

Don’t worry about all of these deployments, many or most of which you might never actually use. Deployments are free, even the unused ones. As Vercel itself says if you request to delete a deployment: Deployments that are not actively receiving any traffic do not generate any costs nor count towards any limits.

It is Vercel’s intention that there should be no need to delete deployments. Instead, they intend that almost all deployments will simply be left to exist, even the unused ones. (Because of this there are no retention periods or simple ways to delete multiple deployments all at once.)

Creating an account

You will need to sign up for a Vercel account. Luckily, you can simply sign up using your GitHub account/credentials without having to create a separate username or password.

  1. On the Vercel website select the “Sign Up” button. (A shortcut URL is: https://vercel.com/signup.)
  2. Select the “Continue with GitHub” button.
  3. A pop-up window will appear asking you for permission to access your GitHub information. Press the green “Authorize Vercel” button to continue.

Importing a repository

After you create your account you will then see an “Import Git Repository” screen. The default listed is likely to be the actual freesewing/freesewing repository owned by FreeSewing. However, you should instead import your own personal fork of the FreeSewing repository.

  1. In the dropdown menu, select “Add a GitHub Account”.
  2. Select your personal GitHub account from the list.
  3. Select the “Only select repositories” radio button.
  4. In “Select repositories” drop-down menu, select your freesewing repository.
  5. Click the green “Install” button.
  6. Confirm that you are giving permission to access the repository by entering your GitHub password.
  7. Finally, back at the Import Git Repository screen complete the import by selecting the white “Import” button.

Creating a project

You will next be taken to the Configure Project page where you can create a project.

By default, the default Root Directory will be sites/dev. The Root Directory setting will determine the build type for the project.

  • sites/dev will build a freesewing.dev website
  • sites/org will build a freesewing.org website
  1. Change the name of the project, if you wish. Names can consist of alphanumeric lowercase and hyphen characters.
  2. Change the Root Directory to the desired setting, as described above.
  3. In the Build & Development Settings, add yarn build as the Build Command override. (All the other settings will work fine with the default values.)
  4. Press the white “Deploy” button.

Vercel will then create the project and start building the project’s first deployment based on the current develop branch. Once the build completes you will see a Congratulations page, with a preview image of the website home page.

About deployments

As mentioned previously, Vercel will eventually create and build many deployments for your project. One is known as the production deployment, based on the configured Production Branch of the repository (by default the branch named main). All other deployments are referred to as preview deployments, including ones based on the develop branch (unless you change the Production Branch in the Project Settings to develop instead of `main).

Created deployments include:

  1. The initial production deployment. (Because you don’t have a branch named main in your repository, Vercel will instead create the initial production deployment from the default develop branch.)
  2. A new preview deployment every time you update your develop branch in GitHub (for example, whenever you sync it with the latest freesewing/freesewing updates)
  3. A new preview deployment for every new branch you push to GitHub
  4. A new preview deployment for every update you make to these new branches when you push to GitHub
  5. A new preview deployment for every update you make to your existing branches when you push to GitHub

If you have multiple projects for the same repository (for example, if you have both sites/org and sites/dev projects), then multiple deployments will be created every time you push to GitHub.

Deployments are automatically created by Vercel. However, because free Hobby accounts are limited to 1 concurrent build, new deployments might be queued before they start building.

Once they start, deployments take about 4-5 minutes to build for /sites/dev and 16-18 minutes or so for sites/org.

The Vercel Dashboard

You will manage your account and projects from the Vercel Dashboard page, https://vercel.com/dashboard.

The default Overview tab at the top of the Dashboard page will show your repositories and projects. Click on a project name to go to its project page.

Project pages

The default Project tab at the top of the project page will show the the production deployment and some of the most recent preview deployments for that project.

Click on the Deployments tab to see all of the project’s deployments. Click on a deployment name to go to its deployment page.

Click on the Settings tab to see the project’s settings.

Deployment pages

On the default Deployment tab at the top of the deployment page you will see information about the deployment.

Under Domains you will see one or more URLs that can be used to access the deployment. These are also the URLs that you can share with others so they can view your deployments.

  • URLs containing hash characters link to the deployment for a single commit.
  • URLs without a hash point to the deployment for the latest version of that branch.

If you ever want to delete a deployment you can do so on its deployment page, under the ”…” three dots menu.

Usage and Billing

Vercel’s free Hobby accounts come with 100 GB of bandwidth and 100 hours of build time each month. This should be at least 10-15x the amount you will actually use in a month, so do not worry about this.

If you want to check your usage, please seee the Usage tab at the top of the Dashboard page.

Disabling automatic deployments

You can disable and enable automatic deployments for a project, for example if you wish to temporarily stop them while working on a bug that prevents successful builds.

On the Project Settings page, select Git from the menu on the left. Change the Ignored Build Step behavior from “Automatic” to “Don’t build anything”.

Getting started with CodespacesGetting started on Linux