@01.software/init

Ecommerce Template

Minimal Next.js commerce storefront template with a pluggable payment-adapter seam. A single source scaffolds either supported payment provider; the active provider for a generated app is recorded in app-config.ts and its keys live in .env.local.example.

What is included

• App Router storefront routes for product listing, product detail, cart, checkout, and payment success.
• Adapter boundaries under lib/commerce and lib/payment.
• Demo commerce and payment adapters backed by data/mock-catalog.json.
• Automatic @01.software/sdk/server commerce adapter when 01.software SDK credentials are present.
• A payment-adapter registry (lib/payment/provider.server.ts) that selects a provider from environment credentials, with first-class adapters for:
  • PortOne — @portone/browser-sdk/v2 on the client, @portone/server-sdk on the server.
  • TossPayments — the TossPayments browser SDK on the client, the TossPayments payment REST API on the server.
• A theming seam: a CSS-variable token layer in app/globals.css plus Tailwind.
• Server-side order pricing, stock checks, and payment sync invariants.
• Server-authoritative cart operations through the template's own route handlers, backed by commerce.cart.*.
• An HttpOnly cart cookie containing only the unguessable cartToken; client JavaScript receives rendered cart views but never owns the authoritative cart or token, and no cart contents are persisted in localStorage.
• Checkout through orders.checkout({ cartId }), with orders resolved after payment by orders.getByPaymentId.

Scaffolding vs. this in-repo source

This directory is the single in-repo source and intentionally ships both payment adapters so it builds and tests with every provider present. create-01-software-app copies it, prunes the unused payment adapter (and its dependency), generates app-config.ts and .env.local.example from templates/registry.json, and pins the SDK version — producing a self-contained single-provider app.

To add a new payment provider, see Add a payment provider below.

Run locally

pnpm install
pnpm dev

Without SDK or payment credentials, the app uses demo providers:

# 01.software keys omitted -> demo catalog plus in-memory cart/checkout
# payment keys omitted -> local demo payment completion

The mock adapter emulates the server cart and checkout flow in memory for zero-backend demos. Redirect and success routes resolve the same in-process checkout model without writing a local order index.

To use the Console ecommerce SDK adapter, set both SDK keys:

NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY=pk_...
SOFTWARE_SECRET_KEY=sk_...
SOFTWARE_API_URL=https://your-console-origin.example
SOFTWARE_SHIPPING_AMOUNT=3000
SOFTWARE_FREE_SHIPPING_ABOVE_AMOUNT=100000

SOFTWARE_API_URL, SOFTWARE_SHIPPING_AMOUNT, and SOFTWARE_FREE_SHIPPING_ABOVE_AMOUNT are optional. The SDK adapter uses Console cart and order APIs for the full server-authoritative flow: route handlers call commerce.cart.*, checkout calls orders.checkout({ cartId }), and return/webhook/success reconciliation resolves orders by payment id through orders.getByPaymentId.

Payment provider keys

PortOne

PORTONE_API_SECRET=...
NEXT_PUBLIC_PORTONE_STORE_ID=store_...
NEXT_PUBLIC_PORTONE_CHANNEL_KEY=channel-key-...
NEXT_PUBLIC_PORTONE_PAY_METHOD=CARD
PORTONE_WEBHOOK_SECRET=...

NEXT_PUBLIC_PORTONE_PAY_METHOD is optional and defaults to CARD. PORTONE_WEBHOOK_SECRET is required in production. For local development without signed webhooks, set PORTONE_ALLOW_UNSIGNED_WEBHOOKS=true. When the secret is present, the webhook route verifies PortOne webhook signatures through @portone/server-sdk.

TossPayments

TOSSPAYMENTS_SECRET_KEY=test_sk_...
NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY=test_ck_...
NEXT_PUBLIC_TOSSPAYMENTS_CUSTOMER_KEY=customer_...

NEXT_PUBLIC_TOSSPAYMENTS_CUSTOMER_KEY is optional. If omitted, the browser SDK uses TossPayments' anonymous customer key. TossPayments redirects back with paymentKey, orderId, and amount; /api/checkout/payment-return re-fetches the provider payment, rejects a tampered redirect amount, captures with the PG-verified amount, then redirects to the success page. Success-page reconciliation re-fetches the provider payment again and places the Console checkout through orders.confirmPayment, where the open checkout quote remains the authoritative amount check. TOSSPAYMENTS_API_BASE_URL is optional and defaults to https://api.tosspayments.com/v1.

Add a payment provider

• Add lib/payment/adapters/<pg>.ts implementing the PaymentProvider port and exporting create<Pg>Provider plus has<Pg>Credentials.
• Register it in lib/payment/provider.server.ts inside a matching pair of scaffold:provider:<id> markers (import + registry entry).
• Add a ClientPaymentRequest union case in lib/payment/types.ts.
• Add a client branch (and its scaffold:provider:<id> markers) in components/checkout/checkout-form.tsx.
• Add the provider to templates/registry.json so the scaffolder offers it.

The template depends on the published @01.software/sdk package so it can be copied out of this monorepo and installed as a standalone Next.js app.

The starter software product listing uses a simple products query followed by per-product detail lookups so the UI can share one normalized product-detail shape. It isolates individual detail failures with Promise.allSettled. For a larger storefront, replace that listing path with the Console tenant's preferred catalog/listing API shape.

Verify

pnpm test
pnpm check-types
pnpm lint
pnpm build

Important boundary

The browser never owns the authoritative cart or cart capability tokens. It talks to the template's cart route handlers, which keep the cart server-authoritative and store only an HttpOnly cart cookie in the browser. Client components may keep rendered cart views in memory, but cart mutations and checkout always return to the server cart. Checkout attaches customer and shipping details to that server cart, converts it with orders.checkout({ cartId }), and then synchronizes payment state. After payment, order lookup uses orders.getByPaymentId, so the template does not need a file-backed order index.