Installing Soames

Soames is made of four pieces: WPGraphQL (the API), the Soames plugin and Soames WordPress theme (the WordPress side), and soames-astro-theme (the front end, consumed by a site project such as soames-site). Getting Started covers the happy path; this guide goes deeper — installing each piece, customizing the front end, and deploying to production.

The pieces

WPGraphQL — exposes WordPress over a GraphQL API at /graphql.
Soames plugin (soames-wordpress-plugin) — site settings, the assets REST endpoint, Header/Footer menu locations, the hero header controls (title, caption, background image, overlay), the Soames content blocks, and the Documentation post type.
Soames WordPress theme (soames-wordpress-theme) — a minimal classic theme that turns on the WordPress features the front end relies on.
soames-astro-theme — the Astro front-end theme; a site project consumes it as an integration.

Install the WordPress side

1. WPGraphQL

Install from the plugin directory: Plugins → Add New, search WPGraphQL, then Install and Activate.

2. Soames plugin

The Soames plugin is custom (not in the directory), so install it directly: zip the soames-wordpress-plugin folder and use Plugins → Add New → Upload Plugin, or drop the folder into wp-content/plugins/ via SFTP or git. Then Activate. Always deploy the plugin whole (its editor JavaScript and PHP must match).

3. Soames WordPress theme

Install the same way: Appearance → Themes → Add New → Upload Theme with a zip of soames-wordpress-theme, or place it in wp-content/themes/. Then Activate.

For the rest of the WordPress configuration — permalinks, Soames settings, homepage/blog page, and menus — follow the Getting Started guide.

Set up the front-end project

Option A — Clone the site project (recommended)

The quickest path is the prebuilt site project, which already wires in the Soames Astro theme:

git clone <your-soames-site-repo> soames-site
cd soames-site
npm install

Option B — Add Soames to a new Astro site

To start fresh, scaffold an Astro project and add the theme integration. Install the front-end dependencies:

npm create astro@latest
npm install @astrojs/react react react-dom sharp soames-astro-theme

import { defineConfig } from 'astro/config';
import soamesTheme from 'soames-astro-theme';

process.loadEnvFile?.('.env');

export default defineConfig({
  output: 'static',
  integrations: [
    soamesTheme({ wordpressUrl: process.env.WORDPRESS_GRAPHQL_URL }),
  ],
});

The integration registers React, sources content from WordPress, and injects the page, blog, and documentation routes. Add your .env with WORDPRESS_GRAPHQL_URL, then run npm run dev.

Pin your Node version

Soames needs Node ≥ 18.20.8. Pin a version so collaborators get it automatically:

echo "22" > .nvmrc
nvm use

Customize with component overrides

The theme’s components, layouts, and styles are imported internally as @theme/<path>. To override any of them, create a file at the matching path under src/overrides/ in your site — a whole-file replacement, resolved at build time, with no change at the import site:

src/overrides/components/Footer.tsx        replaces @theme/components/Footer.tsx
src/overrides/layouts/Base.astro           replaces @theme/layouts/Base.astro
src/overrides/styles/site-overrides.css    your site-wide CSS

This is how a site customizes Soames without forking the theme.

Build and deploy

npm run build      # static site in dist/
npm run preview    # serve the production build locally

Deploy the dist/ output to any static host (Netlify, Vercel, Cloudflare Pages, S3/CloudFront, etc.). In your host’s settings, use build command npm run build, publish directory dist, and set the WORDPRESS_GRAPHQL_URL environment variable (it isn’t committed — .env is git-ignored).

Because the output is static, the site is rebuilt to reflect content changes. Trigger a rebuild after publishing in WordPress — via a host deploy hook, a “rebuild” button, or a schedule.

HTTPS and CloudFlare

Serve WordPress over HTTPS end-to-end, and make sure the WordPress Address and Site Address both use https. On multisite, set each site’s siteurl/home via Network Admin → Sites → Edit → Settings (not Settings → General, and not WP_SITEURL/WP_HOME constants).

CloudFlare: prefer SSL mode Full (strict) with a certificate on the origin. CloudFlare “Flexible” SSL (HTTPS to the browser, HTTP to the origin) makes WordPress mis-detect the scheme and causes mixed-content and redirect-loop issues. If you must use Flexible, add a header-based HTTPS detection snippet to wp-config.php.

Verify

https://your-site.com/graphql returns data (and any firewall/WAF allows it).
npm run build completes and dist/ contains your pages.
The deployed site shows your content, menus, logo, and footer.

Documentation