Deploying Soames to Netlify

This guide walks through deploying a Soames site to Netlify. Soames is a headless setup: WordPress is the content backend, and the soames-site repository builds a static Astro front end that Netlify hosts on its CDN. Deploying means connecting that repository to Netlify, giving it the build settings and WordPress endpoints, and pointing your domain at it.

You only do this once per site. After it’s set up, every push to the main branch rebuilds and redeploys automatically. To also rebuild when content changes in WordPress, see Setting Up a Publish Webhook.

Before you start

A Netlify account with access to the Git provider (GitHub) that hosts soames-site.
The WordPress endpoints for your backend: the GraphQL URL and the site base URL. Use HTTPS for both so the static output has no mixed-content references.
The soames-site repository builds with Node 22 and outputs to dist/.

Connect the repository

In Netlify, choose Add new site → Import an existing project.
Connect your Git provider and authorize Netlify to access the account or organization that owns soames-site.
Select the soames-site repository, and set the production branch to main.

Build settings

The build command is npm run build and the publish directory is dist. Rather than typing these into the Netlify UI, keep them in a netlify.toml file at the repository root so the configuration is version-controlled:

[build]
  command = "npm run build"
  publish = "dist"

[build.environment]
  NODE_VERSION = "22"

Setting NODE_VERSION here ensures Netlify builds with Node 22; older versions are too old for Astro.

Environment variables

The build needs to know where your WordPress backend lives. In Netlify, go to Site configuration → Environment variables and add:

WORDPRESS_GRAPHQL_URL   https://your-wordpress-host/graphql
WORDPRESS_BASE_URL      https://your-wordpress-host

Use the real HTTPS URLs of your WordPress install. These are read at build time to fetch content; they are not secrets, but keep them accurate — a wrong or non-HTTPS URL is the most common cause of a failed or mixed-content build.

First deploy and verify

Trigger the first build (Netlify starts one automatically when the site is created, or use Deploys → Trigger deploy).
Watch the deploy log. A successful build ends by publishing the dist directory.
Open the temporary Netlify URL (e.g. your-site.netlify.app) and confirm pages, posts, and Knowledge Base articles render with content from WordPress.

Custom domain and HTTPS

Point your domain at the Netlify site using the DNS records Netlify shows under Domain management — typically an A/ALIAS record for the apex domain and a CNAME for www. If your DNS is managed by Cloudflare (a common setup for Soames), add those records in Cloudflare and set the SSL/TLS mode to Full (strict) so encryption is validated end-to-end between Cloudflare, Netlify, and the visitor. Netlify provisions the TLS certificate automatically once DNS resolves.

Continuous deployment

Once connected, Netlify rebuilds and redeploys on every push to main. Merging a change to the site or updating the soames-astro-theme dependency and pushing is all it takes to ship code changes.

Code pushes cover changes to the site and theme. To rebuild when someone publishes content in WordPress, set up the build hook described in Setting Up a Publish Webhook.

Documentation