[!TIP]
Questions or issues? Check our Discord for help.
Why Paper?
Ship faster, customize everything. Paper is a new release—expect some rough edges—but every component is built with real-world e-commerce in mind. This is a foundation you can actually build on.
🛒 Open Checkout (v2)
The checkout is where most storefronts fall apart or fall short. Paper's doesn't — and checkout v2 aligns it with the rest of the stack: App Router, Server Components, server actions, and the same BFF session as the storefront (no client-side urql or browser Saleor tokens).
Storefront cart Checkout surface
───────────── ────────────────
src/lib/checkout.ts src/app/(checkout)/checkout/
cookie + mutations → CheckoutSessionLoader (RSC)
@paper/session-bridge CheckoutApp → steps + payment
buildCheckoutPath() /order/{hmac} (guest confirmation)
- Server-first cart — RSC loads checkout +
me on entry; client context is a cache of server truth (CheckoutDataProvider).
- URL-driven steps —
?step=contact|shipping|payment updates shallowly (no full page refetch per click); browser Back walks the funnel.
- Dedicated confirmation —
/order/{hmac} after pay (URL frozen; status/tracking refresh from Saleor). /order/{saleorId} from email is redacted until we recognize you. Legacy /checkout/complete?order= redirects. See checkout-guest-order.md.
- Extensible payments — Registry (
INTEGRATED_GATEWAYS) with Stripe + Dummy; add gateways via checkout-payment-gateways skill.
- Shared BFF auth — Sign-in via
/api/auth/login; session resolved server-side (resolveSessionUser — guest / authenticated / unavailable).
- Multi-step, mobile-first — Focused forms, international address fields, composable step components.
Developer docs: start at skills/saleor-paper-storefront/rules/paper-surfaces.md, then checkout-management.md. Forks on the old urql checkout: migrations/atomic/2026-06-checkout-v2/.
🌍 International by Default
One codebase, many markets. Browse URLs are /{locale}/{channel}/… — e.g. /en/us/products/hoodie (English, US market, USD) and /pl/pl/products/bluza (Polish, Poland, PLN, with a translated catalog slug when set in Saleor) — with legacy /{channel}/… paths redirecting automatically. Each locale gets its own cached catalog payload, translated product copy from Saleor, per-channel pricing and currency, and hreflang/canonical metadata (including per-locale product/category handles).
- Region picker — header control switches locale and channel together (language + market + currency), remapping catalog URLs to each language’s canonical slug
- Three string systems — Saleor catalog translations, merchant-editable storefront content (CMS), and code-owned UI via next-intl (
messages/{locale}.json)
- Seven built-in locales —
en, pl, de, fr, fi, nb, ko (extend via LOCALE_DEFINITIONS in src/config/locale.ts)
- Optional translated URL slugs — Saleor Dashboard can set per-language handles for products, categories, collections, and pages; Paper resolves, redirects, links, and hreflang accordingly (ADR 0004)
Storefront channels are explicit. Saleor may have many channels (B2B, wholesale, internal regions); Paper only exposes the slugs you configure via STOREFRONT_CHANNELS. Disallowed channel URLs return 404. For a single-channel store, set NEXT_PUBLIC_DEFAULT_CHANNEL only—the footer channel selector is hidden automatically.
Developer docs: docs/international-storefront.md · ADRs 0001 / 0002 / 0004 · skills ui-locale-routing / ui-i18n
📱 Product Pages Done Right
The hard parts are solved. Adapt the look, keep the logic.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
