Static-first SSG delivery

Static-first SSG publishes complete HTML for stable and discovered storefront routes. WordPress remains the content and artifact control plane, while the static host serves the known-good generated deployment. React activates afterward to provide cart, account, search, language, CMS scripts, and other interactive behavior.

Use this mode for a public launch when initial rendering, crawlable route content, predictable metadata, and resilience during a temporary backend failure are priorities. For immediate content iteration before launch, use dynamic SPA delivery.

Current delivery status

The current storefront implementation provides:

• complete static documents for products, posts, pages, authors, post taxonomies, and

WooCommerce taxonomies;

• route-specific hydration data for the React handoff;
• static navigation, CMS markup, CSS, reviewed scripts, and shortcode presentation;
• generated canonical metadata, robots rules, sitemaps, feeds, and AI discovery files;
• signed shell registration and WordPress artifact generation;
• Action Scheduler processing with WP-Cron fallback;
• revision and dependency tracking with safe known-good fallback behavior;
• fail-closed handling for private, password-protected, and invalid routes.

Rollout is still site-specific. Validate every configured language, special page, content family, host build hook, and rollback path before making static-first delivery public.

Build and publish

Configure the public frontend values, then build from the frontend workspace:

pnpm install --frozen-lockfile
pnpm build

Publish apps/storefront/dist. The build discovers public WordPress routes, writes their HTML and hydration payloads, and generates the route and discovery files used by the static host.

Set VITE_SITE_URL to the final public origin so canonical, sitemap, feed, and discovery URLs are correct. Production deployments must set their own VITE_GRAPHQL_ENDPOINT.

Configure static-first delivery

Set these values in the frontend hosting provider:

STOREFRONT_ARTIFACT_MODE=artifact
STOREFRONT_ARTIFACT_DELIVERY=static-first
STOREFRONT_ARTIFACT_ORIGIN=https://backend.example.com
STOREFRONT_ARTIFACT_SITE_KEY=unique-site-key
STOREFRONT_ARTIFACT_SIGNING_SECRET=same-secret-as-wordpress
VITE_ARTIFACT_ROUTE_HYDRATION=true

Use a different site key for every public site. The signing secret must be identical in WordPress and the frontend environment and contain at least 32 characters. Store it only in server-side or provider secret configuration; never expose it through a VITE_ variable or commit it.

VITE_ARTIFACT_ROUTE_HYDRATION=true controls the React handoff for supported artifact routes. It does not disable SSG and does not make the deployment equivalent to the dynamic SPA mode.

Configure WordPress

In Appearance > FunkyCommerce > Build & Deploy:

1. set the public frontend URL;
2. set Dynamic content delivery to shadow mode;
3. enter the same artifact site key and signing secret used by the deployment;
4. configure and test the frontend host build webhook;
5. confirm the shell registration and generation queue are healthy;
6. inspect representative shadow artifacts;
7. switch to artifact delivery only after acceptance passes.

The current FunkyCommerce admin label is retained for compatibility and will be renamed to Superfunky in a future release.

Publishing and freshness

WordPress invalidation and artifact regeneration happen automatically, but the public static HTML changes only when a storefront build is published. This lets editors group related changes while the previous known-good deployment remains public.

When changes are ready:

1. use Rebuild storefront in the WordPress admin bar;
2. confirm the hosting provider starts the deployment;
3. wait for a successful build;
4. verify the affected routes and generated metadata on the live deployment.

For Netlify, the Build status badge ID reports deployment state below the rebuild action. Other static hosts can use the same webhook even when they do not provide that badge.

Acceptance checklist

Before promotion, verify:

• the homepage and one normal WordPress page;
• one post, author, category, and tag;
• one product and every enabled product taxonomy;
• custom shop, privacy, terms, login, registration, and recovery paths;
• every configured language and its fallback behavior;
• canonical URLs, titles, descriptions, robots directives, and structured data;
• sitemap, feed, and AI discovery outputs;
• static CMS styles, scripts, shortcodes, internal links, and media;
• cart, checkout, account, search, language switching, and browser restoration;
• password-protected and private content remains excluded;
• a failed build leaves the previous deployment available;
• rollback to the previous known-good deployment works.

Operations and rollback

Monitor build duration as route counts grow. Current builds intentionally generate detailed route hydration data; a larger route inventory therefore increases build work. Monitor failed or exhausted jobs for the current shell rather than aggregate historical artifact counts.

If acceptance fails:

1. keep or return WordPress artifact generation to shadow mode;
2. redeploy the previous known-good static release;
3. confirm the public host no longer serves rejected artifacts;
4. correct the failing route, integration, or environment value in staging;
5. repeat the acceptance checklist before promotion.

To temporarily return to runtime-fetched content during active development, deploy the dynamic SPA configuration. Changing STOREFRONT_ARTIFACT_MODE alone is not sufficient because the standard build still generates static routes.

Next: prepare DNS.