# Deploy to Netlify

> Put your Astro site live on Netlify with automatic deploys from Git, preview every change before it goes live, and roll back in one click.

Source: https://viralistic.nl/help/astro/deploy-to-netlify

Every Viralistic Astro site is hosted on Netlify. Netlify builds the site from your Git repository, publishes it on a global network and rebuilds it every time the code or content changes. This article is for anyone putting a site live for the first time, or taking over an existing one. You will connect the repository, understand how deploys and previews work, and learn what to do when a build fails.

## Before you start

You need:

- The site in a Git repository, for example on GitHub.
- A Netlify account with access to the team that should own the site.
- A `netlify.toml` file in the root of the repository with the build settings:

```toml
[build]
  command = "pnpm build"
  publish = "dist"
```

`pnpm build` runs Astro's build, and `dist` is the folder it writes the finished site to. Viralistic projects also pin the Node version in `.nvmrc`, which Netlify reads, and Netlify detects pnpm from the `pnpm-lock.yaml` file.

> **Tip:** Keep redirects and headers in the same `netlify.toml`. Then every setting that affects how the site is served lives in the repository, with its history, instead of in someone's memory.

## Create the project on Netlify

1. Log in to Netlify.
2. Add a new project and choose to import an existing project from Git.
3. Connect your Git provider and allow Netlify to access the repository.
4. Select the repository.
5. Check the build settings. Netlify reads them from `netlify.toml`: build command `pnpm build`, publish directory `dist`, and your main branch as the production branch.
6. If the site needs secrets or keys (for example a Sanity token), add them as environment variables now.
7. Start the deploy and follow the log.

When it finishes, the site is live on a free address ending in `.netlify.app`. You can change the first part of that address by renaming the project. To use your own domain, see [Connect your domain](https://viralistic.nl/help/astro/connect-your-domain).

## How deploys work from now on

| You do this                                | Netlify does this                                                         |
| ------------------------------------------ | ------------------------------------------------------------------------- |
| Push or merge to the main branch           | Builds and publishes the live site                                        |
| Open a pull request                        | Builds a deploy preview with its own URL and links it on the pull request |
| Push more commits to that pull request     | Updates the deploy preview                                                |
| Call a build hook (for example from a CMS) | Rebuilds the live site with the latest content                            |

Deploy previews are the safest way to work: check the change on a real URL, share it with a colleague, and merge only when it is right.

> **Note:** A deploy preview is public to anyone with the link. Do not put confidential content in a pull request you would not want to show.

## When a build fails

A failed build never replaces the live site. Visitors keep seeing the last successful version while you fix the problem.

1. Open the failed deploy in Netlify and read the deploy log.
2. Scroll to the first error, not the last line. The first error is usually the cause.
3. Match it to one of the common causes:

| The log mentions                  | Likely cause                                    | Fix                                                |
| --------------------------------- | ----------------------------------------------- | -------------------------------------------------- |
| An unrecognised or unexpected key | A frontmatter field the schema does not know    | Fix the typo or remove the field                   |
| A required field                  | A page is missing a field such as `description` | Add the field                                      |
| An image that cannot be found     | A wrong path or a missing file in `src/assets`  | Correct the path or add the file                   |
| The lockfile                      | `pnpm-lock.yaml` does not match `package.json`  | Run `pnpm install` locally and commit the lockfile |

4. Reproduce it locally with `pnpm build` if the log is unclear. The same error appears on your machine.
5. Push the fix. Netlify builds again automatically.

## Roll back a bad deploy

If a deploy succeeded but something on the live site is wrong:

1. Open the list of deploys in your Netlify project.
2. Select the last deploy that was fine.
3. Publish that deploy. The live site switches back within seconds.
4. Fix the problem in the repository through a pull request, then check that the new deploy is the one published.

## Keep it tidy

- Give the right people access through Netlify's team settings, never by sharing one login. See [Share logins and access safely](https://viralistic.nl/help/account/share-access-safely).
- Turn on deploy notifications (email or a chat tool) for failed builds, so you hear about problems before visitors do.
- Run `pnpm check` and `pnpm build` locally before pushing larger changes.

## Next steps

- [Connect your domain](https://viralistic.nl/help/astro/connect-your-domain)
- [Keep your rankings when you relaunch](https://viralistic.nl/help/astro/redirects)
- [Edit your site with Claude Code](https://viralistic.nl/help/astro/edit-your-site-with-claude-code)