Documentation

Installing Soames

Soames is made of three pieces: WPGraphQL (the API), the Soames plugin (the WordPress side), and soames-astro-theme (the front end, consumed by your site project). 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, previews, the Knowledge Base post type, and the redirect that sends anyone landing on WordPress itself over to your published site.
  • soames-astro-theme — the Astro front-end theme, published to npm; a site project consumes it as an integration.

The WordPress side is one plugin. Soames used to ship a small companion WordPress theme alongside it, and older instructions tell you to install one. As of Soames 1.0.0 that theme is retired: the plugin declares the featured-image and page-excerpt support the front end needs, and owns the front-end redirect. Nothing to install, and no constraint on which theme you keep active. Upgrading from 0.9.0? Just deactivate the old Soames theme — the plugin takes over on its own.

Install the WordPress side

1. WPGraphQL

Install from the plugin directory: Plugins → Add New, search WPGraphQL, then Install and Activate. Do this first — Soames declares WPGraphQL as a required plugin, so WordPress will not let you activate Soames without it.

2. Soames plugin

Soames isn’t in the WordPress.org plugin directory, so you install it from a release zip. Download soames-wordpress-plugin.zip, then Plugins → Add New → Upload Plugin, install, and Activate. A Soames menu appears in the sidebar.

That download URL always resolves to the newest release, so it never goes stale and there is no version number to track. Every release and its notes are on the releases page, and the download page has the requirements and a step-by-step walkthrough.

If you deploy the plugin by other means — SFTP, or git into wp-content/plugins/ — always deploy it whole. Its editor JavaScript and its PHP have to match; a mismatch breaks block rendering while the editor still looks fine.

3. Updating later

Updates are manual, on purpose. Because Soames isn’t distributed through the WordPress.org directory, it doesn’t appear in your dashboard’s update list and nothing will prompt you. To update: download the zip again, upload it the same way, and choose Replace current with uploaded when WordPress asks. Your settings and content are untouched. It’s worth checking the releases page now and then.

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 — Start from the starter template (recommended)

soames-astro-starter is a GitHub template repository: the Soames Astro theme already wired up, and nothing else. Click Use this template → Create a new repository to get your own repo with no shared history, then:

git clone https://github.com/your-username/your-site.git
cd your-site
cp .env.example .env      # then set WORDPRESS_GRAPHQL_URL
nvm use
npm install
npm run dev

Or clone it directly and start your own history with rm -rf .git && git init.

A note on which repo to start from. soames-site is the source of this very website — a real, deployed Soames implementation, and a useful thing to read. It is not a starter: it carries soames.app’s own CSS, that site’s visual-regression baselines, and a deployment bound to one host account. Start from the starter and look at soames-site for reference.

Option B — Add Soames to an existing Astro site

If you already have an Astro project, install the front-end dependencies:

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

Register the integration in astro.config.mjs:

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 Knowledge Base routes. Add your .env with WORDPRESS_GRAPHQL_URL, then run npm run dev.

Keep the two halves in step

The plugin and the front-end theme are two halves of one contract: the plugin emits the block markup, the theme renders it. A block added on one side renders as empty space on the other, so upgrade them together.

  • Soames plugin 1.0.0 or newer pairs with soames-astro-theme 0.1.18 or newer.
  • Update the front end with npm install soames-astro-theme@latest. While the theme is pre-1.0 a ^0.1.x range covers patch releases only, so moving to a new minor is a deliberate bump.

The download page carries the current compatibility table.

Pin your Node version

Soames needs Node ≥ 18.20.8. The starter ships an .nvmrc already; in your own project, 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. Copy the theme’s version out of node_modules/soames-astro-theme/src/<path> as your starting point. Because an override replaces the whole file, it stops receiving upstream changes to that file — so override the smallest thing that gets you what you want.

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). The starter includes a netlify.toml with the build command, publish directory, and Node version already set.

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. Paste a Build hook URL under Soames → Settings and the plugin will do it for you on every publish.

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.
  • Visiting your WordPress address sends you to your Soames site — that’s the plugin’s redirect, and it confirms the front-end URL is set. Switch it off with the Front-end redirection checkbox while you’re still setting things up.
Links
Contact
fritz followed by ASCII 0x40 followed by the domain name orbisoftware dot com.

© 2026 orbi / software
Built with Soames, Astro, and WordPress