freesewing/markdown/dev/tutorials/getting-started-vercel/en.md

title	order
Getting started with Vercel	14

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.

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

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 lab.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.org website, used to test changes to that website.

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. The reason why Vercel builds a deployment for every push and update is so 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.

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 acccount 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
• sites/lab will build a lab.freesewing.dev website/app

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. Don't change any of the Build & Development Settings. The default values will work fine.
4. Press 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 (in about 3-4 minutes or so) 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 develop branch of the repository. All other deployments are referred to as preview deployments.

Created deployments include:

1. The initial production deployment for the 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/lab and sites/dev projects),i then multiple deployments will be created everytime 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 3-4 minutes or so to build.

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.

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

Verce'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.

• A shortcut URL is https://vercel.com/dashboard/usage
• Or, https://vercel.com/account/billing will show a summary of your usage.