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:

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

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.
• 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
• Keep your rankings when you relaunch
• Edit your site with Claude Code