Skip to main content

Understand Headless Turbo Theme Architecture

The Headless Turbo theme is a React single-page application served through Fastify. Fastify also provides a same-origin proxy between the browser and Fynd Commerce.

Customer
  └── Hosting platform
        └── Fastify server
              ├── React storefront and static assets
              └── /service, /ext, /graphql
                    └── Fynd Commerce APIs

Understand the Frontend​

  • React 18 and React Router 6 render storefront pages and handle navigation.
  • Redux and FPI manage state and commerce actions.
  • GraphQL requests use @gofynd/fdk-store-gql.
  • Webpack 5 compiles JSX, LESS, CSS, SVG, fonts, and images.
  • Lazy routes, extracted CSS, and content-hashed assets improve loading and cacheability.

The main React entry point is theme/app.jsx. Routes are defined in theme/routes.jsx, while GraphQL operations are grouped in theme/queries/.

Trace the Development Request Flow​

Running local dev starts two processes:

  1. Webpack Dev Server runs on TURBO_DEV_PORT and provides hot module replacement.
  2. Fastify runs on PORT, forwards storefront traffic to Webpack, and proxies API traffic to PROXY_TARGET.

The browser always opens the Fastify URL (by default http://localhost:8080), not the Webpack port.

Trace the Production Request Flow​

After build, Fastify:

  • Serves the generated dist/ assets
  • Returns index.html for client-side application routes
  • Proxies /service, /ext, and /graphql to Fynd Commerce
  • Injects the application ID and token into the HTML at request time
  • Compresses responses and applies security headers
  • Hardens upstream cookies and validates CSRF tokens for mutations
  • Exposes /__health and /__version

Hashed assets receive long-lived cache headers. The SPA shell is returned with no-cache so storefront releases are not pinned by browser caching.

Configure the Runtime​

Fastify reads .env and then overlays platform environment variables. This means deployment-platform values take precedence over local file values.

Application credentials are exposed through window.__APP_CREDENTIALS__ so the browser FPI client can initialize.

warning

APPLICATION_TOKEN is visible to storefront visitors and scripts. It must be a public-scope application token. Never configure a partner-level, private, or privileged token.

Apply Security Controls​

The included Fastify runtime provides:

  • Same-origin API proxying
  • Double-submit CSRF validation for production mutations
  • Content Security Policy in report-only mode by default
  • HSTS in production
  • Secure and SameSite=Lax cookie hardening
  • Cross-origin opener, embedder, and resource policies
  • Escaping of values injected into inline scripts

If you adapt the Headless Turbo theme to another serverless runtime, reproduce these controls. Serving only dist/ omits the proxy, runtime credential injection, CSRF validation, and server security headers.

Further Reading​