Storefront SDK

@wocart/storefront is the storefront's connection to Wocart. It reads the store's catalog, delivery data and saved content, and it sends baskets, reviews, OTP codes and orders through the server that owns the rules.

Your Astro pages decide how the store looks. The SDK decides what is safe to read and send. Prices, stock, delivery fees, discounts and whether an order is accepted stay on the server.

A fixed storefront is a real choice

You do not need Wocart's editing tools to build a storefront. An Astro site with this SDK and your own components is complete. The optional Theme SDK adds merchant editing, saved page documents and preview.

Quick start

Install the SDK, create the server-only client, render a catalog and a product page.

How it works

Layers, page types, result shapes, caching and the security boundary.

Basket and checkout

Place an order, verify a phone, track conversions and abandonment.

Who this is for

If you are…	Start with
New to Wocart	Quick start
Building a custom Astro storefront for one store	Quick start, then Astro actions and routes
Making an editable theme	The theme starter, then this SDK for the commerce data
Looking for one method or type	The API reference

The guide begins with one working page and adds one area at a time. You can stop when your storefront does what you need.

What the SDK gives you

Typed reads. Products, categories, pages, menus, rates and config arrive as the shapes the server validated.
Predictable failures. Reads resolve to null, [] or {} and report the cause through onError. Writes return a result you can branch on.
A browser-safe root. The root entry has no client factory and no API key. Browser code imports it freely; the key stays on the server.
Astro adapters. Same-origin routes, the place-order form engine and the middleware that renders a refused form are ready to wire.
Browser helpers. The basket store, OTP state machine, image URLs for any media host, money formatting and the store's WhatsApp link are part of the package.

What you install

Code
npm install --save-exact @wocart/storefront@3.1.0
npm install zod

zod 4.x is a peer dependency. The package is ESM-only and its tooling needs Node 22.12 or newer. @wocart/storefront 3.x reads platform v7: a store updates its platform and its storefront together. The helpers under @wocart/storefront/astro are written for Astro 7; the rest of the package does not import Astro.

Four imports, one boundary

Import	Runs in	What it holds
`@wocart/storefront`	Browser and server	Types, money and image helpers, reference data, basket, OTP machine, route paths, Meta payloads
`@wocart/storefront/server`	Server only	`createStoreClient`, preview and revalidation checks
`@wocart/storefront/astro`	Server only	`resolveStoreRequest`, `createStorefrontRoutes`, `createProxyEndpoint`, `placeOrderInput`, `executePlaceOrder`, `runFormAction`, `lookupOrder`, `notFound`
`@wocart/storefront/review-media`	Browser only	Photo resizing and voice recording for a review form

The store key has one home

@wocart/storefront/server holds the store API key. Never import it from a browser script, island or public variable. Browser code calls your own same-origin routes, and those routes call the SDK on the server.

What the client covers

Namespace	Use it for
`config`	Store identity, languages, checkout policy and feature flags
`products`	Product lists, product detail and reviews
`collections`	A merchant's curated product lists and collection pages
`categories`	Catalog navigation
`pages`	Legal and CMS pages, landing pages
`menus`	The store's navigation menus
`pageData`	The saved page document for an editable theme
`shipping`	Default delivery prices per wilaya
`geo`	Wilayas and communes
`cart`	Server re-pricing, coupons and delivery quotes
`orders`	Order creation, OTP, abandoned checkout and tracking

What it does not do

The SDK does not render pages, store the browser's basket on the server, upload images, write page documents, or decide a theme's layout, copy and motion. It also does not make a stale browser price trustworthy.

Commerce rules live in the server. If a feature needs a new rule, change the server contract first, then use it here.

Guide map

Page	What it covers
Quick start	Install, create the client, render a catalog and a product page
How it works	Layers, page types, results, caching and the security boundary
Store config and languages	Store settings, checkout policy, localization and theme text
Products and collections	Lists, detail, variants, offers, quantity pricing and categories
Reviews	Read reviews, prove a purchase, upload media and submit
Pages and menus	Legal pages, navigation, landing pages and saved page documents
Basket and quotes	The browser basket, server validation, coupons and free delivery
Checkout and OTP	Place an order, verify a phone, track conversions and abandonment
Delivery and geography	Default rates, real quotes, wilayas and communes
Money, images, WhatsApp and Meta events	Display helpers and browser events that stay consistent
Astro actions and routes	Form actions, middleware and the same-origin API
Preview and revalidation	Draft previews and instant publish for editable themes
Testing a storefront	What to test, the definition of done and common mistakes
Public API surface	Every export per entry point, the client namespaces and the schemas

The API reference is generated from the published TypeScript declarations. This guide follows @wocart/storefront 3.1.0.

Quick start