Dynamic SPA delivery

Dynamic SPA delivery runs the Superfunky React storefront as an optimized production application without publishing route-specific generated HTML. The browser loads the application shell and requests current public content and commerce data from WordPress.

Use this mode while a site is under active development, when editors need published WordPress changes to appear without waiting for a storefront rebuild, or for an internal preview where search-engine rendering is not the priority.

How it differs from local development

Do not run pnpm dev on a public domain. The Vite development server is designed for local development, includes development behavior, and is not a production web server.

A production SPA still uses minified, versioned assets from vite build. It differs from static-first SSG only in document delivery: the host serves the shared index.html application shell instead of generated HTML for every public route.

Current implementation status

The storefront already supports client-only startup. When the root element does not contain prerendered content, React mounts immediately and reads from the configured WordPress GraphQL endpoint.

The repository's standard pnpm build command currently includes the prerender step. STOREFRONT_ARTIFACT_MODE=off disables WordPress artifact delivery, but it does not skip that prerender step. A production SPA deployment must therefore use a dedicated build command that runs Vite without the prerender script.

Until that command is included in the public release, treat SPA production delivery as an advanced deployment configuration and verify it after every storefront update.

Build the SPA

From the frontend workspace, install locked dependencies and run the storefront's Vite build without the prerender command:

pnpm install --frozen-lockfile
pnpm --filter @funky/storefront exec vite build

Publish apps/storefront/dist.

Keep the normal pnpm build command for static-first acceptance. Do not replace it globally if the same repository also produces an SSG deployment.

Configure public values

Set public build values in the hosting provider:

VITE_GRAPHQL_ENDPOINT=https://backend.example.com/graphql
VITE_SITE_URL=https://example.com
STOREFRONT_ARTIFACT_MODE=off

Set optional public Stripe and geolocation values as described in frontend setup. Never put WordPress passwords, signing secrets, payment secrets, or webhook credentials in VITE_ variables.

Configure application routing

The host must serve real assets first and rewrite all unmatched storefront routes to index.html. On a Netlify-style host:

/*  /index.html  200

Use the equivalent rewrite on Cloudflare Pages, Vercel, Nginx, Apache, or another host. Without this rule, direct visits to paths such as /shop/product-name/ return a host 404 before React can resolve the route.

Do not rewrite backend API, media, webhook, or WordPress administration traffic through the storefront. Those requests remain on the backend hostname.

Content freshness

Frontend code changes appear after a new frontend deployment. Published WordPress data is requested at runtime, so it does not require an SSG rebuild to become available.

The storefront can render a last-known-good browser cache first and refresh it in the background. During acceptance:

1. publish a harmless WordPress content change;
2. load the affected storefront route in a private browser window;
3. confirm the request targets the intended GraphQL endpoint;
4. confirm the current content appears after loading or background revalidation;
5. test direct navigation and browser refresh on nested routes.

Browser caching, a CDN, or a GraphQL cache can still delay changes independently of SSG. Inspect response headers and purge only the affected cache when freshness is unexpected.

Trade-offs

Dynamic SPA delivery provides rapid content iteration and avoids build-trigger waiting, but it has important costs:

• the initial document contains an application shell rather than complete route content;
• search and social crawlers receive less useful HTML unless they execute the application;
• the first useful render depends on JavaScript and backend availability;
• a slow or unavailable WordPress endpoint is visible to new visitors;
• route metadata is produced after application startup rather than arriving in generated

HTML.

Use noindex or access controls for unfinished public previews when appropriate. Do not rely on an unlinked URL as a security boundary.

Move from SPA to SSG

No content migration is required. The SPA and SSG modes use the same React storefront and WordPress backend.

1. Complete route, SEO, checkout, language, and content acceptance.
2. Configure the build webhook, artifact identity, and signing secret.
3. Validate artifact generation in shadow mode.
4. Change the host build command to the standard pnpm build.
5. Deploy to a draft URL and inspect representative generated documents.
6. Enable static-first delivery and complete the rollback checks in the

SSG guide.

Next: set up static-first SSG delivery or prepare DNS.