> ## Documentation Index
> Fetch the complete documentation index at: https://www.commercengine.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Astro
> First-class Astro wrapper with cookie-backed sessions, SSR pages, API routes, middleware, and static prerendering support.
The `@commercengine/storefront/astro` package provides an Astro-specific wrapper around the core Storefront SDK. It gives you three accessors — `publicStorefront()`, `serverStorefront()`, and `clientStorefront()` — with automatic cookie-backed token management for SSR and hybrid rendering.
### NPM Package
Astro integration for Commerce Engine Storefront SDK. Import from `@commercengine/storefront/astro`.
## Installation
```bash npm theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install @commercengine/storefront
```
```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark"}}
pnpm add @commercengine/storefront
```
```bash yarn theme={"theme":{"light":"github-light","dark":"github-dark"}}
yarn add @commercengine/storefront
```
## Quick Start
Add your store credentials to `.env`:
```bash .env theme={"theme":{"light":"github-light","dark":"github-dark"}}
PUBLIC_STORE_ID=your-store-id
PUBLIC_API_KEY=your-api-key
```
Astro uses the `PUBLIC_` prefix for client-exposed env vars (accessed via `import.meta.env`).
A shared config imported by both client and server storefronts:
```typescript src/lib/storefront-config.ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Environment } from "@commercengine/storefront";
import type { AstroStorefrontConfig } from "@commercengine/storefront/astro";
export const storefrontConfig: AstroStorefrontConfig = {
storeId: import.meta.env.PUBLIC_STORE_ID,
apiKey: import.meta.env.PUBLIC_API_KEY,
environment: Environment.Staging, // or Environment.Production
tokenStorageOptions: { prefix: "myapp_" },
};
```
```typescript src/lib/storefront.ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { createAstroStorefront } from "@commercengine/storefront/astro";
import { storefrontConfig } from "./storefront-config";
export const storefront = createAstroStorefront(storefrontConfig);
```
The server entry is isolated from the client entry to prevent server code from leaking into browser bundles.
```typescript src/lib/server-storefront.ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { createAstroServerStorefront } from "@commercengine/storefront/astro/server";
import { storefrontConfig } from "./storefront-config";
export const serverStorefront = createAstroServerStorefront(storefrontConfig);
```
Never import `server-storefront.ts` in client scripts or framework islands. Server storefront must only be used in `.astro` frontmatter, API routes, or middleware.
```astro src/layouts/Layout.astro theme={"theme":{"light":"github-light","dark":"github-dark"}}
---
// src/layouts/Layout.astro
---
```
The `astro:page-load` listener is important because Astro's `ClientRouter` runs bundled scripts once and then swaps pages on later navigations. Listening for this event ensures bootstrap runs after each navigation.
## Accessor Rules
Use the right accessor for each context:
| Context | Accessor | Import From |
| ------------------------------------------------ | ---------------------------------------------------- | --------------------------- |
| Frontmatter — public reads (catalog, categories) | `storefront.publicStorefront()` | `src/lib/storefront` |
| Browser scripts / client islands | `storefront.clientStorefront()` | `src/lib/storefront` |
| Client bootstrap | `storefront.bootstrap()` | `src/lib/storefront` |
| SSR pages (`.astro` with `output: "server"`) | `serverStorefront.serverStorefront(Astro.cookies)` | `src/lib/server-storefront` |
| API routes (`src/pages/api/*.ts`) | `serverStorefront.serverStorefront(context.cookies)` | `src/lib/server-storefront` |
| Middleware | `serverStorefront.serverStorefront(context.cookies)` | `src/lib/server-storefront` |
`serverStorefront()` requires passing `Astro.cookies` (or `context.cookies`) because Astro has no global request context. This call is synchronous — no `await` needed. `clientStorefront()` **throws** if called on the server.
## Key Patterns
### Public Reads in Frontmatter
```astro theme={"theme":{"light":"github-light","dark":"github-dark"}}
---
import { storefront } from "../lib/storefront";
const sdk = storefront.publicStorefront();
const { data } = await sdk.catalog.listCategories();
const categories = data?.categories ?? [];
---
```
### Session-Aware Server Page
```astro src/pages/account.astro theme={"theme":{"light":"github-light","dark":"github-dark"}}
---
// src/pages/account.astro (SSR)
import { serverStorefront } from "../lib/server-storefront";
const sdk = serverStorefront.serverStorefront(Astro.cookies);
const { data, error } = await sdk.customer.getCustomer();
if (error) return Astro.redirect("/login");
---
Welcome, {data?.customer?.first_name}
```
### API Routes (Session-Bound)
```typescript src/pages/api/wishlist.ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import type { APIRoute } from "astro";
import { serverStorefront } from "../../lib/server-storefront";
export const GET: APIRoute = async ({ cookies }) => {
const sdk = serverStorefront.serverStorefront(cookies);
const { data, error } = await sdk.cart.getWishlist();
if (error) return new Response(JSON.stringify({ error: error.message }), { status: 500 });
return new Response(JSON.stringify(data));
};
export const POST: APIRoute = async ({ cookies, request }) => {
const body = await request.json();
const sdk = serverStorefront.serverStorefront(cookies);
const { data, error } = await sdk.cart.addToWishlist({
product_id: body.productId,
variant_id: body.variantId ?? null,
});
if (error) return new Response(JSON.stringify({ error: error.message }), { status: 500 });
return new Response(JSON.stringify(data));
};
```
### Middleware
Use Astro middleware for auth guards and injecting session data into `context.locals`:
```typescript src/middleware.ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { defineMiddleware } from "astro:middleware";
import { serverStorefront } from "./lib/server-storefront";
export const onRequest = defineMiddleware(async (context, next) => {
const sdk = serverStorefront.serverStorefront(context.cookies);
const userId = await sdk.session.peekUserId();
if (context.url.pathname.startsWith("/account") && !userId) {
return context.redirect("/login");
}
context.locals.userId = userId;
return next();
});
```
### Client-Side Fetching (After Hydration)
Once the app is hydrated, use the client accessors directly in scripts or framework islands:
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// In a