---
title: "Storefront runtime"
description: "How Astro composes templates, creates request context, resolves themes, and hydrates interactive components."
canonical_url: "https://nyxel.dev/docs/storefront-sdk"
markdown_url: "https://nyxel.dev/docs/storefront-sdk.md"
---

# Storefront runtime
URL: /docs/storefront-sdk
LLM index: /llms.txt
Description: How Astro composes templates, creates request context, resolves themes, and hydrates interactive components.

# Storefront runtime

The storefront is an Astro server application. It resolves a route, loads Shopify data and a Nyxel template, then recursively composes the template through framework adapters.

![Nyxel reference storefront product page for Slides in light mode.](/site-media/storefront-product.png)

## From request to HTML

Astro middleware creates a request-local context with the URL, locale, market, headers, cookies, Shopify client, cart identity, and Preview session. The route layer adds resources such as the active product or collection and selects the corresponding template document.

`@nyxel/astro` walks the template tree. For each node it looks up the normalized manifest, resolves settings and dynamic bindings, applies theme values, renders named child regions, and dispatches the component to its Svelte, Astro, or React adapter.

Astro owns recursion because it is the one layer that can compose all supported renderers. A component only needs to understand its semantic props:

```ts
interface NyxelNodeProps<Settings, Theme, Regions> {
	settings: Settings
	theme: Theme
	sources: SourceContext
	regions: Regions
	editor?: EditorRenderContext
}
```

## Server-first rendering

Components render on the server unless their contract declares a hydration policy. `load`, `idle`, `visible`, and `media` map to Astro client directives. Interactive islands should remain small and communicate across framework boundaries through explicit browser events or HTTP contracts rather than assuming shared component state.

The header, product form, and cart drawer illustrate this boundary. They can hydrate independently, while cart data is managed by Hydrogen and open/close commands cross islands through a page-level event.

## Routes and commerce

The reference storefront includes home, product, collection, page, search, cart, password, sitemap, and error behavior, with locale-prefixed forms where the request context supplies a locale. Explicit API routes handle cart and search before any catch-all theme route.

![Nyxel reference storefront collection page with filtering and sorting controls.](/site-media/storefront-collection.png)

Collection state is URL-backed. Filter and sort controls update query parameters, route data refreshes through the Shopify request context, and the component renders applied filters and result state from that URL. Cart mutations use Hydrogen’s cart handlers and preserve Shopify checkout as the final purchase surface.

## Theme CSS

The reference theme combines Tailwind utilities with four Nyxel-owned layers:

| Layer          | Responsibility                                                    |
| -------------- | ----------------------------------------------------------------- |
| Theme tokens   | Type, spacing, radius, layout, and semantic aliases               |
| Element styles | Classless HTML defaults using theme and color-scheme variables    |
| Primitives     | Shared buttons, page width, rich text, cards, and layout behavior |
| Runtime theme  | Merchant values and generated `[data-color-scheme]` variables     |

Component CSS should use these tokens instead of hard-coded theme colors. A component can select or inherit a color scheme; nested controls such as market and theme switchers must retain their own readable foreground and surface variables.

Canvas responses include the same scoped CSS, runtime variables, fonts, and absolute asset URLs. Shadow DOM prevents the theme reset from changing editor chrome.

## Development services

The Astro integration mounts development-only registry, template, preset, schema-default, Canvas render, and Preview session handlers. Their business logic lives in framework-neutral runtime services, while Astro converts Requests and Responses at the host boundary.

A production editor platform will implement authenticated persistence and rendering behind equivalent contracts. The file-backed development endpoints are never a production API.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).