freesewing/sites/dev/docs/tutorials/getting-started-vercel/readme.mdx

---
title: Getting started with Vercel
sidebar_position: 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.

:::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][v] select the "Sign Up" button.
   (A shortcut URL is: [https://vercel.com/signup][vsu].)
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.

[v]: https://vercel.com
[vsu]: https://vercel.com/signup

## 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][vd].

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.

[vd]: https://vercel.com/dashboard

## 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.

- A shortcut URL is [https://vercel.com/dashboard/usage][vu]
- Or, [https://vercel.com/account/billing][vb] will show a summary
  of your usage.

## 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".

[vu]: https://vercel.com/dashboard/usage
[vb]: https://vercel.com/account/billing