Request Lifecycle
What happens between a request arriving and a response leaving? One file answers it: src/server/index.ts builds the Hono app and registers every stage in order. Each stage either answers the request itself or puts something on the Hono context that later stages read, so the order decides what your own code can reach.
The pipeline below is the one your fork ships with. You can reorder it, drop a stage, or add your own, as long as a stage that reads a context value still runs after the stage that sets it. The stages that come from @scayle/storefront are registered by name, so changing one means passing it different options or replacing the call, not editing the package.
The pipeline

Two handlers sit outside the chain. app.onError(createStorefrontErrorHandler()) catches anything a stage throws, and app.notFound(createStorefrontNotFoundHandler()) answers a path no route matched. Errors and Logging covers both.
What each stage adds
The health route answers GET /api/up with { status: 'up' } and returns. It is registered before every global middleware on purpose, so a readiness probe never loads a session or builds a registry.
Compression, the nosniff header, and static asset serving come next, followed by OpenTelemetry tracing. Static assets are served from disk in a production build only. Under pnpm dev, Vite answers asset requests before they reach the app, and tracing sits after asset serving so an asset request produces no span.
createStorefrontRuntime({ mapperRegistry, serviceRegistry }) is the stage that fills the context. It composes several middleware of its own, in this order:
- The
X-Powered-Byheader, unless you setDISABLE_POWERED_BY_HEADERat build time, then the response cache. The cache marks the route cacheable or not asctx.get('isRouteCacheable'), which later stages read. See Caching. config, thenstorage, thenstorefront. The storefront context carries the resolved country, the Storefront API client, and the cache. A request that matches no country gets no storefront context, and the stages after it skip their work rather than fail.- Sitemap routes, when you configure
sitemaps. - The trailing-slash redirect, then the country path redirect. Both skip a path that is
/apior starts with/api/, so the API and analytics routes keep the paths their clients post to. request, the inbound request described below.- The mapper and service registries, as
ctx.get('mappers')andctx.get('services'). - The session, as
ctx.get('session'). On a cacheable route it skips the storage read and sets no cookie, because a shared cache drops any response carryingSet-Cookie. - Inertia, as
ctx.get('inertia'), plus the renderer thatctx.render()calls.
After the runtime, your own stages run. The CMS middleware relaxes the Content Security Policy for an editor session and redirects a preview request onto the real content path, both reading ctx.get('services').cms. securityHeadersMiddleware writes the baseline security headers and sits after the CMS one deliberately, so the editor's framing relaxation survives. The analytics route accepts the browser's event beacon on POST /api/analytics/events and answers without rendering a page. It mounts bare and under the country prefix, because a beacon cannot send the X-Shop-Country-Id header an oRPC call uses to name its country.
sharedDataMiddleware declares the Inertia props every page receives, built from ctx.get('services') and ctx.get('request'). Pages and Controllers lists them.
The API router mounts last but one, because the SSR router's country segment would otherwise swallow /api. The SSR router mounts the page routes, under a country prefix when your country selector uses one. Routing and Countries covers the selectors.
The inbound request
ctx.get('request') is an IncomingRequest: the values that describe this one request, separate from the shop it runs against. Service factories, controllers, and oRPC handlers all read the same object, so they cannot disagree about what arrived.
| Member | What it holds |
|---|---|
headers | Inbound headers with lower-cased keys, including cookie and authorization. |
query | Inbound query parameters, keyed as sent. A missing key is absent from the map, and a repeated key keeps its first value. |
originalIp | Visitor IP from the header named by clientIpHeader, X-Forwarded-For when you set none, or undefined when the header is absent, empty, or not a valid IP address. |
origin | The public origin of this request, for example https://shop.example.com. |
url | The public URL: origin plus path and query string. One immutable URL shared by every reader, so editing searchParams or assigning pathname throws. Copy it with new URL(request.url) when you need a writable one. |
session | The request session. |
isRouteCacheable | A live read of the response cache flag, also available as ctx.get('isRouteCacheable'). false until the response cache middleware has run. |
origin is the public host your visitors see, which is not always the host the request arrived on. Public origin explains how the SDK resolves it and the rule for absolute URLs that follows from it.
Never forward headers wholesale to an upstream API, since it carries the cookie and the authorization header. Pick the fields you need.
Reading request.session throws until the session middleware has run, so read it inside a method rather than in a factory body. Session and Authentication covers what it stores.
Kinds of request
A first page load carries no X-Inertia header. The server resolves every prop, renders Vue to HTML, and answers with a full document. A deferred prop is left out of this response and fetched afterwards.
An Inertia visit carries X-Inertia: true. The server answers with the page object as JSON instead of HTML, and server-only props are dropped from it. The browser swaps the page component without a document reload.
A partial reload is an Inertia visit that also names what it wants. X-Inertia-Partial-Component has to match the component the server is about to render, and X-Inertia-Partial-Data or X-Inertia-Partial-Except lists the props. The server resolves only those and answers with the same JSON shape. This is what router.reload({ only: [...] }) sends, and what fetches a deferred prop after the first load.
A fourth kind is not a page at all. An oRPC call goes to /api, carries a JSON body, and never touches the Inertia renderer. It gets the same storefront, request, mappers, and services a controller gets, and answers 400 when the request resolved no country. RPC API covers writing one.
The response cache treats these differently. A partial reload is never cached, because its body depends on the headers it sent. A cacheable page response varies on x-inertia and x-shop-country-id, so a shared cache stores the HTML and the JSON under the same URL as separate entries.
Outgoing calls
Every call your server makes through the global fetch goes through one dispatcher: the calls to the Storefront API, the Checkout API, Storyblok, Constructor, and the S3 sitemap source. src/server/index.ts registers it once at startup with setGlobalDispatcher(createOutboundDispatcher()). Contentful, Contentstack, and Amplience bring their own HTTP clients, so the dispatcher does not cover them.
src/server/outbound-dispatcher.ts sets these limits:
- A call fails when the response headers take longer than 3 seconds, or when no body chunk arrives for 3 seconds.
- A connection that takes longer than 5 seconds to open fails.
- The server opens at most 32 connections to one origin,
CONNECTIONS_PER_ORIGIN. Another call to that origin waits for a free connection, and the 3-second timers do not run during that wait. When an upstream stalls every connection to its origin, the nth concurrent call to it fails after aboutceil(n / 32) × 3seconds. - An idle connection stays open for 30 seconds, so later calls reuse it.
- The dispatcher honors
HTTP_PROXY,HTTPS_PROXY, andNO_PROXYfrom the process environment.
A failed call rejects like any other network failure, and the code that made it decides what the customer sees. You own the file. Change the constants, or pass another timeout to createOutboundDispatcher. Limits for a single origin belong in the factory option of the undici Agent, see the undici Agent documentation.
Add your own middleware
A stage of your own is a Hono middleware registered in src/server/index.ts. Put it after createStorefrontRuntime(...) when it needs the config, the storefront context, the session, or a registry, which is nearly always.
This one rejects a request whose Accept-Language names a language your shop does not serve. Registered with app.use, it runs for page requests and for oRPC calls under /api:
Register it after the runtime and before the routers:
At that point the context carries everything StorefrontVariables declares: config, storage, storefront, request, mappers, services, session, inertia, and isRouteCacheable. Treat storefront, mappers, and services as possibly unset: a request that matched no country has none of them, and app.use runs on every path, including /api.
To check it worked, run pnpm dev and send a request with a language your shop does not serve:
The response comes back 406, and the error handler logs the HTTPException at warn, since a 4xx is the application answering rather than failing. Without the middleware the same request renders the page.
Two more places take a middleware. app.use('/path/*', handler) scopes one to a path prefix. The CMS stages are registered with '/*', which matches every path, so they run for every request and check inside the stage whether it is an editor or preview request. And ssrRouter.use('*', handler) in src/server/ssr-routes.ts scopes one to page routes only, which is where the SCAYLE Panel redirect lookup, the history encryption stage (see Sign out), and the auth guard on /account/* sit, so an oRPC call and the analytics beacon never pay for them.
Reading ctx.get('config') before the runtime has run leaves it unset, and securityHeadersMiddleware throws with a message naming the registration order.