Build a Next.js Storefront

Recommended App Router architecture: server data layer, cookies, store code vs country.

On this page

This is the recommended data layer for an Aiminaabee storefront on Next.js App Router. Other frameworks can still call the same Store API; copy these rules, not the file names.

These guides (and the store-front-development skill) specify implementation only: SDK, store code, cookies, region, cart, checkout API order, auth. They do not specify UI, layout, or branding. Build apps/template-storefront or any similar shop from this data layer. If an app’s implementation disagrees, fix the app. If its UI differs, that is expected.

What stays the same for every shop

One JS SDK client. Pass a store code as the first argument of every sdk.store.* method.
Store code is an env value (NEXT_PUBLIC_DEFAULT_STORE_CODE). It is not the country in the URL.
Catalog, cart, checkout, and customer calls run on the server (src/lib/data/*.ts with "use server").
Login token and cart ID live in httpOnly cookies, not localStorage.
Product prices need a region. Resolve region from the customer's country, then pass region_id.
Checkout API order: email → address → shipping → payment → complete cart. Screens may merge; do not skip the API steps.
After login or signup, transfer the guest cart to the customer.

Pages, components, and styling are yours. Do not invent a second backend.

Environment

Variable	Purpose
`AIMINAABEE_BACKEND_URL`	Aiminaabee API origin (server). Defaults to `http://localhost:3000`.
`NEXT_PUBLIC_AIMINAABEE_PUBLISHABLE_KEY`	Publishable API key for Store routes.
`NEXT_PUBLIC_DEFAULT_STORE_CODE`	Store slug passed to `sdk.store.*`.
`NEXT_PUBLIC_DEFAULT_REGION`	Optional default country ISO (for example `us` or `mv`).

Set up the SDK as shown in Connect to Aiminaabee. Create a publishable key as shown in Publishable API Keys.

Data-layer files

Recommended names for the Next.js data layer (not a required page tree):

src/lib/config.ts
src/lib/store-code.ts
src/lib/data/cookies.ts
src/lib/data/regions.ts
src/lib/data/products.ts
src/lib/data/cart.ts
src/lib/data/customer.ts
src/lib/data/fulfillment.ts
src/lib/data/payment.ts
src/lib/data/orders.ts
src/lib/data/categories.ts
src/lib/data/collections.ts

[countryCode] in the URL (or equivalent) is the shopper's country (prices, taxes, shipping). storeCode is the Aiminaabee store. Pass storeCode into server actions; pass countryCode into getRegion(storeCode, countryCode). Route and component names are yours.

Cookies

Cookie	Purpose
`_aiminaabee_jwt`	Customer JWT (httpOnly).
`_aiminaabee_cart_id`	Current cart ID (httpOnly).
`_aiminaabee_cache_id`	Suffix for Next.js cache tags.

Read them only in server modules (cookies.ts). After cart or customer mutations, revalidate tags carts, customers, and fulfillment as needed.

Next guides

Connect — SDK client.
Regions — list regions and map country → region.
Products — list and retrieve with region_id.
Carts — getOrSetCart, line items.
Checkout — five steps.
Customers — login, transfer cart, profile.

Client-only examples later in this section (useEffect in an SPA) still work. For Next.js, prefer the server pattern on this page.