Shared Astro theme for the Soames ecosystem — WordPress as a headless CMS, static output, React islands. Successor to soames-gatsby-theme (see ORBI-23/24/25).

Quick start

Starting a new site? Don't wire this up by hand — use soames-astro-starter and click Use this template. It's this theme already configured, and nothing else.

The instructions below are for adding the theme to an Astro project you already have.

Install

npm install soames-astro-theme

Usage

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

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

The integration registers @astrojs/react, sources content from WordPress at build time, injects the page routes (front page, WP pages, blog archive, blog posts), authorizes WP image domains, and installs the theme-shadow resolver.

Component overrides (the shadowing successor)

Astro has no built-in component shadowing. This theme provides it via a Vite resolver: theme files are imported as @theme/<path>, and a site overrides any of them by creating a file at the matching path under src/overrides/.

src/overrides/components/Footer.tsx   → replaces the theme's components/Footer.tsx
src/overrides/layouts/Base.astro      → replaces the theme's layouts/Base.astro

Whole-file replacement, resolved at build time, zero changes at the import site — the direct successor to Gatsby component shadowing.

WordPress sourcing notes

• Sources via WPGraphQL (fetch()), with Site Assets from the Soames plugin REST endpoint (/wp-json/soames/v1/settings).
• Wordfence gotcha: some WP installs' WAF 403-blocks GraphQL whose first selection-set field is pages/posts. lib/wp.ts aliases the root field (e.g. wpPages: pages) to pass; the durable fix is a Wordfence allowlist rule.

Status

Published to npm (ORBI-25). Under active migration — routing/URL parity, menu interactivity, and remaining shortcodes are being completed phase by phase.