docs
/
Client Integration

Build a web store

Develop against the checked-in Next.js storefront, trace catalog and pricing, then add explicit server validation and customer ownership.

Build on appmint-examples/nextjs-store to get a catalog, product detail and priced browser cart. This walkthrough uses the actual project and its pinned dependency ranges; the example does not include customer sign-in or checkout. You will identify which code runs on the server, verify a quote, and prepare the boundaries needed to extend it.

1. Start the project

git clone https://github.com/JacLight/appmint-examples.git
cd appmint-examples/nextjs-store
cp .env.example .env.local
npm install

Use Node 20+ and configure APPENGINE_ENDPOINT, ORG_ID, APP_ID, APP_KEY, and APP_SECRET in .env.local. Use your controlled organization with one active product. Keep the file ignored; none of these credentials needs a NEXT_PUBLIC_ prefix. The secret stays on the Next.js server; a phone app never ships it (see Phone apps without a secret).

npm run dev

Open port 4100. A request error should remain visible as an error, not be mistaken for an empty catalog. See the complete setup and file map if the application fails to start.

2. Read the catalog on the server

The example's lib/appmint.ts exports get, post, request, and viaServer. These are example functions, not SDK methods. A minimal replacement catalog page can use its existing types:

// app/page.tsx
import Link from 'next/link';
import { get } from '@/lib/appmint';
import type { Paged, Product } from '@/lib/types';

export const dynamic = 'force-dynamic';
export default async function Catalog() {
  const page = await get<Paged<Product>>('storefront/products?p=1&ps=12');
  return <main>
    <h1>Products</h1>
    <ul>{page.data.map((row) => <li key={row.sk}>
      <Link href={`/product/${encodeURIComponent(row.data.sku)}`}>
        {row.data.title || row.data.name}
      </Link>
      {' — '}{row.data.calculatedPrice?.finalPrice ?? row.data.price}
    </li>)}</ul>
  </main>;
}

The list and each row both have a data field for different purposes. Keep row.sk as the record key, and use the SKU/slug expected by product detail. This example renders the upstream numeric price; add currency formatting from the actual currency contract rather than assuming every organization uses dollars.

The default get is application-only. Customer-specific prices require reading the current request session and passing its token as the fourth argument to viaServer. An app token identifies the integration; it does not sign in a shopper.

3. Trace the browser cart

Open lib/cart-storage.ts and components/CartView.tsx. The local cart stores SKU, name, quantity and cached unit price. The component submits lines with coupon and a fixed destination, then displays the returned summary. The call has this shape:

const summary = await post<CartSummary>('storefront/pricing/calculate-cart', {
  productItems: lines.map((line) => ({
    sku: line.sku, quantity: line.quantity, name: line.name,
    price: line.unitPrice, unitPrice: line.unitPrice, itemType: 'product',
  })),
  shippingAddress: destination,
  couponCode: coupon || undefined,
});

This is a fragment inside the cart component, using its existing post, CartSummary, lines and state. destination must come from validated address input when replacing the demo's fixed Dallas address. Rendering summary.total prevents client arithmetic from drifting from the returned quote. Clear the old summary on a failed request; when valid === false, display the coupon verdict even though HTTP succeeded.

Do not interpret the request's cached price as authoritative. The backend recomputes normal SKU prices but has a fallback to submitted prices after a pricing failure. Validate the product/variant on your server and test that tampered or unknown items cannot proceed through your checkout.

4. Put validation in a dedicated route

The sample catch-all forwards broad prefixes. Replace browser pricing with POST /api/price and use the full server proxy example for a request-owned SDK route. That variant requires separately installing the source SDK and its server factory. Alternatively retain the demo transport and call viaServer('POST', 'storefront/pricing/calculate-cart', validatedBody, customerToken) from your dedicated route.

Whichever transport you choose, enforce the same application contract: fixed endpoint and tenant, permitted method, JSON input, positive integer quantity, supported SKU/variant, chosen address and coupon fields, origin/CSRF protection, and the current request's customer cookie. Strip client totals and privileged fields. Forward meaningful upstream errors and map network failure to 503. Neither a prefix check nor hiding credentials implements authorization by itself.

In the browser, replace the pricing call with same-origin fetch('/api/price', …) and parse the body once. This lets the route validate data before it attaches application authority.

5. Add a session before private customer data

Implement a dedicated login route that calls profile/customer/signin, handles requiresTwoFactor, and creates your HTTP-only session only after receiving a customer token. The sample appmint_token cookie reader is not a complete login flow. Follow Authentication for token lifetimes and ownership.

Use client-data/profile, storefront/cart/mine, and client-data/orders for private customer views. Never accept a URL customer ID as proof of ownership. Keep the customer token per request; shared server state should contain only safely reusable application identity.

6. Separate quote, saved cart and checkout

The sample local cart is not persisted to sf_cart. A full implementation needs:

  1. Restore storefront/cart/mine using the customer session.
  2. Calculate the selected items, address and coupon, retaining the returned cartId.
  3. Persist the calculated cart using POST storefront/cart/update/:cartId and its sf_cart record envelope.
  4. Read back the same cart and serialize later saves so an older response cannot overwrite the newest quantity.
  5. Use the configured provider test flow, then submit the actual buyer and genuine payment reference to checkout and reconcile the order.

Calculation can create a cart record, but it does not by itself persist the complete edited basket, place an order, or charge a card. Do not add a button that submits a made-up payment reference to make this demo appear complete.

7. Verify the extension

Run npx tsc --noEmit and npm run build. Stop the development process and use npm run start for a production-build check on port 4100.

Exercise valid and unknown products, a rejected coupon, no shipping coverage, network failure, a stale customer session, and concurrent customers. If adding saved carts, confirm the last edited quantity survives a fresh request. If adding payment, reconcile the actual test-provider transaction and customer order before declaring success. The provided example has no test script and no built-in provider test harness.

The Remix version demonstrates the same server boundary with loaders/actions and an additional reservation flow. The SDK reference documents exact supported methods and the current route mismatches.