@spree/docs 0.1.0

package/dist/developer/storefront/nextjs/deployment.md

@@ -0,0 +1,180 @@
+---
+title: Deployment
+description: Deploy the Spree Next.js Storefront to Vercel, Docker, or any Node.js host
+---
+
+## Environment Variables
+
+Set these variables in your hosting platform's dashboard or `.env` file.
+
+### Required
+
+| Variable | Description |
+|----------|-------------|
+| `SPREE_API_URL` | Your Spree API endpoint (e.g., `https://api.mystore.com`) |
+| `SPREE_PUBLISHABLE_KEY` | Publishable API key from your Spree admin |
+
+> **NOTE:** These are server-side only variables — no `NEXT_PUBLIC_` prefix needed since all API calls happen in Server Actions.
+
+### Optional
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GTM_ID` | Google Tag Manager container ID | _(disabled)_ |
+| `SENTRY_DSN` | Sentry DSN for error tracking | _(disabled)_ |
+| `SENTRY_ORG` | Sentry organization slug | _(none)_ |
+| `SENTRY_PROJECT` | Sentry project slug | _(none)_ |
+| `SENTRY_AUTH_TOKEN` | Sentry auth token (for source maps in CI) | _(none)_ |
+
+## Production Build
+
+```bash
+npm run build
+npm start
+```
+
+The build output is a standalone Next.js application. The `npm start` command starts the production server.
+
+## Vercel
+
+Vercel is the recommended deployment platform for Next.js applications.
+
+### One-Click Deploy
+
+1. Push your code to GitHub
+2. Go to [vercel.com/new](https://vercel.com/new) and import your repository
+3. Add environment variables (`SPREE_API_URL`, `SPREE_PUBLISHABLE_KEY`)
+4. Click **Deploy**
+
+Vercel automatically detects the Next.js framework and configures the build settings.
+
+### Vercel CLI
+
+```bash
+npm i -g vercel
+vercel
+```
+
+### Preview Deployments
+
+Every pull request gets a unique preview URL, making it easy to test storefront changes before merging. Add your Spree API environment variables to the Vercel project settings so previews connect to your staging API.
+
+## Docker
+
+Create a `Dockerfile` in your project root:
+
+```dockerfile
+FROM node:20-alpine AS base
+
+FROM base AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --production=false
+
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+
+FROM base AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+EXPOSE 3000
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+
+CMD ["node", "server.js"]
+```
+
+> **NOTE:** Enable standalone output in your `next.config.ts` for Docker deployments:
+> 
+>   ```typescript
+  const nextConfig = {
+    output: 'standalone',
+  }
+  ```
+
+Build and run:
+
+```bash
+docker build -t spree-storefront .
+docker run -p 3000:3000 \
+  -e SPREE_API_URL=https://api.mystore.com \
+  -e SPREE_PUBLISHABLE_KEY=your_key \
+  spree-storefront
+```
+
+## Self-Hosted Node.js
+
+For any platform that supports Node.js (Render, Railway, Fly.io, AWS, etc.):
+
+1. Install dependencies and build:
+
+```bash
+npm ci
+npm run build
+```
+
+2. Start the production server:
+
+```bash
+npm start
+```
+
+The server listens on port `3000` by default. Set the `PORT` environment variable to change it.
+
+## CI/CD
+
+### GitHub Actions
+
+```yaml
+name: Deploy Storefront
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - run: npm ci
+      - run: npm run build
+
+      # Add your deployment step here
+      # Example for Vercel:
+      # - uses: amondnet/vercel-action@v25
+      #   with:
+      #     vercel-token: ${{ secrets.VERCEL_TOKEN }}
+      #     vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
+      #     vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
+      #     vercel-args: --prod
+```
+
+## Performance Checklist
+
+Before going to production, verify:
+
+- **API URL** points to your production Spree instance (not `localhost`)
+- **HTTPS** is enabled on both the storefront and the Spree API
+- **CORS** is configured on your Spree API to allow requests from your storefront domain
+- **Sentry** is configured for error monitoring (`SENTRY_DSN`)
+- **GTM/GA4** is set up for analytics (`GTM_ID`)
+- **Cookie security** — the storefront uses `secure: true` for cookies in production (`NODE_ENV=production`)
+- **Caching** — Next.js cache tags are used for efficient revalidation; review your caching strategy for high-traffic stores

package/dist/developer/storefront/nextjs/quickstart.md

@@ -0,0 +1,92 @@
+---
+title: Quickstart
+description: Get started with the Spree Next.js Storefront
+---
+
+The [Spree Storefront](https://github.com/spree/storefront) is a production-ready, headless e-commerce storefront built with Next.js 16, React 19, and the Spree Commerce API v3.
+
+## Tech Stack
+
+- **Next.js 16** - App Router, Server Actions, Turbopack
+- **React 19** - Server Components
+- **Tailwind CSS 4** - Utility-first styling
+- **TypeScript 5** - Full type safety
+- **[@spree/sdk](https://github.com/spree/spree/tree/main/packages/sdk)** - Official Spree Commerce SDK
+- **[@spree/next](https://github.com/spree/spree/tree/main/packages/next)** - Server actions, caching, and cookie-based auth
+- **Sentry** - Error tracking and performance monitoring
+
+## Features
+
+- **Server-First Architecture** - All API calls happen server-side, API keys never exposed to the browser
+- **Secure Authentication** - JWT tokens stored in httpOnly cookies
+- **Product Catalog** - Browse, search, and filter with faceted navigation
+- **Shopping Cart** - Server-side state management
+- **Multi-Step Checkout** - Guest and signed-in users, multi-fulfillment, coupon codes, gift cards, store credit
+- **Stripe Payments** - Credit Cards, Apple Pay, Google Pay, Klarna, Affirm, SEPA and more via [Spree Stripe](https://github.com/spree/spree_stripe)
+- **Google Tag Manager** and **GA4 Ecommerce** event tracking
+- **Customer Account** - Profile, order history, address book, gift cards, saved payment methods
+- **Multi-Region** - Country and currency switching via URL segments
+- **Responsive Design** - Mobile-first Tailwind CSS
+
+## Prerequisites
+
+- Node.js 20+
+- A running Spree Commerce 5.4+ instance
+
+## Installation
+
+### Option 1: Fork the Repository (Recommended)
+
+Fork the repository on GitHub, then clone your fork:
+
+```bash
+git clone https://github.com/YOUR_USERNAME/storefront.git
+cd storefront
+npm install
+```
+
+This gives you a full copy you can customize freely while still being able to pull upstream updates.
+
+### Option 2: Clone Directly
+
+```bash
+git clone https://github.com/spree/storefront.git
+cd storefront
+npm install
+```
+
+## Configuration
+
+Copy the environment file:
+
+```bash
+cp .env.local.example .env.local
+```
+
+Update `.env.local` with your Spree API credentials:
+
+```env
+SPREE_API_URL=http://localhost:3000
+SPREE_PUBLISHABLE_KEY=your_publishable_api_key_here
+```
+
+> **NOTE:** These are server-side only variables — no `NEXT_PUBLIC_` prefix needed since all API calls happen in Server Actions.
+
+See [Deployment](/developer/storefront/nextjs/deployment) for all optional environment variables (Sentry, GTM, etc.).
+
+## Development
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:3001](http://localhost:3001) in your browser.
+
+## Production Build
+
+```bash
+npm run build
+npm start
+```
+
+See the [Deployment](/developer/storefront/nextjs/deployment) guide for Vercel, Docker, and other hosting options.

package/dist/developer/storefront/nextjs/spree-next-package.md

@@ -0,0 +1,314 @@
+---
+title: "@spree/next Package"
+description: Next.js integration library — server actions, caching, and cookie-based auth
+---
+
+The `@spree/next` package provides a complete Next.js integration for Spree Commerce with server actions, automatic cookie management, and full TypeScript support.
+
+## Installation
+
+```bash
+npm install @spree/next @spree/sdk
+```
+
+## Configuration
+
+### Auto-initialization
+
+Set environment variables and the client initializes automatically:
+
+```env
+SPREE_API_URL=https://api.mystore.com
+SPREE_PUBLISHABLE_KEY=spree_pk_xxx
+```
+
+### Explicit initialization
+
+```typescript
+// lib/storefront.ts
+import { initSpreeNext } from '@spree/next';
+
+initSpreeNext({
+  baseUrl: process.env.SPREE_API_URL!,
+  publishableKey: process.env.SPREE_PUBLISHABLE_KEY!,
+  cartCookieName: '_spree_cart_token',     // default
+  accessTokenCookieName: '_spree_jwt',     // default
+  defaultLocale: 'en',
+  defaultCurrency: 'USD',
+  defaultCountry: 'US',
+});
+```
+
+## Data Functions
+
+Plain async functions for reading data in Server Components. Wrap with `"use cache"` in your app for caching.
+
+### Products
+
+```typescript
+import { listProducts, getProduct, getProductFilters } from '@spree/next';
+
+const products = await listProducts({ limit: 25 });
+const product = await getProduct('spree-tote', { expand: ['variants', 'media'] });
+const filters = await getProductFilters({ category_id: 'ctg_123' });
+```
+
+### Categories
+
+```typescript
+import { listCategories, getCategory, listCategoryProducts } from '@spree/next';
+
+const categories = await listCategories({ depth_eq: 1 });
+const category = await getCategory('clothing/shirts');
+const products = await listCategoryProducts('clothing/shirts', { limit: 12 });
+```
+
+### Store & Geography
+
+```typescript
+import { getStore, listCountries, getCountry, listCurrencies, listLocales } from '@spree/next';
+
+const store = await getStore();
+const countries = await listCountries();
+const usa = await getCountry('US');
+const currencies = await listCurrencies();
+const locales = await listLocales();
+```
+
+### Using in Server Components
+
+```typescript
+import { listProducts, listCategories } from '@spree/next';
+
+export default async function ProductsPage() {
+  const products = await listProducts({ limit: 12 });
+  const categories = await listCategories({ depth_eq: 1 });
+
+  return (
+    <div>
+      {products.data.map((product) => (
+        <div key={product.id}>{product.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Server Actions
+
+Server actions handle mutations and auth-dependent reads. They automatically manage cookies for cart tokens and JWT authentication.
+
+### Cart
+
+```typescript
+import { getCart, getOrCreateCart, addItem, updateItem, removeItem, clearCart, associateCart } from '@spree/next';
+
+const cart = await getCart();              // null if no cart
+const cart = await getOrCreateCart();       // creates if needed
+await addItem(variantId, quantity);
+await updateItem(lineItemId, { quantity: 2 });
+await removeItem(lineItemId);
+await clearCart();
+await associateCart();                     // link guest cart to logged-in user
+```
+
+### Checkout
+
+Checkout functions use the implicit cart resolved from cookies. No `orderId` is needed.
+
+```typescript
+import {
+  getCheckout,
+  updateCheckout,
+  getFulfillments,
+  selectDeliveryRate,
+  applyCoupon,
+  removeCoupon,
+  complete,
+} from '@spree/next';
+
+const checkout = await getCheckout();
+await updateCheckout({ shipping_address: { ... }, billing_address: { ... } });
+const fulfillments = await getFulfillments();
+await selectDeliveryRate(fulfillmentId, deliveryRateId);
+await applyCoupon('SAVE20');
+await removeCoupon(promotionId);
+await complete();
+```
+
+### Authentication
+
+```typescript
+import { login, register, logout, getCustomer, updateCustomer } from '@spree/next';
+
+await login(email, password);
+await register(email, password, passwordConfirmation);
+await logout();
+const customer = await getCustomer();   // null if not logged in
+await updateCustomer({ first_name: 'John' });
+```
+
+### Addresses
+
+```typescript
+import { listAddresses, getAddress, createAddress, updateAddress, deleteAddress } from '@spree/next';
+
+const addresses = await listAddresses();
+const address = await getAddress(addressId);
+await createAddress({ first_name: 'John', address1: '123 Main St', ... });
+await updateAddress(addressId, { city: 'Brooklyn' });
+await deleteAddress(addressId);
+```
+
+### Orders
+
+```typescript
+import { listOrders, getOrder } from '@spree/next';
+
+const orders = await listOrders();
+const order = await getOrder(orderId);
+```
+
+### Payment Sessions
+
+Payment session functions use the implicit cart. No `orderId` is needed.
+
+```typescript
+import {
+  createPaymentSession,
+  getPaymentSession,
+  updatePaymentSession,
+  completePaymentSession,
+} from '@spree/next';
+
+const session = await createPaymentSession({ payment_method_id: 'pm_123' });
+
+// Access provider data (e.g., Stripe client secret)
+const clientSecret = session.external_data.client_secret;
+
+const current = await getPaymentSession(sessionId);
+await updatePaymentSession(sessionId, { amount: '50.00' });
+await completePaymentSession(sessionId, { session_result: 'success' });
+```
+
+### Payment Setup Sessions
+
+For saving payment methods outside of checkout (e.g., "Add a credit card" in account settings):
+
+```typescript
+import {
+  createPaymentSetupSession,
+  getPaymentSetupSession,
+  completePaymentSetupSession,
+} from '@spree/next';
+
+const session = await createPaymentSetupSession({ payment_method_id: 'pm_123' });
+const current = await getPaymentSetupSession(sessionId);
+await completePaymentSetupSession(sessionId, { session_result: 'success' });
+```
+
+### Credit Cards & Gift Cards
+
+```typescript
+import { listCreditCards, deleteCreditCard } from '@spree/next';
+import { listGiftCards, getGiftCard } from '@spree/next';
+
+const cards = await listCreditCards();
+await deleteCreditCard(cardId);
+
+const giftCards = await listGiftCards();
+const giftCard = await getGiftCard(giftCardId);
+```
+
+## Using Server Actions in Forms
+
+```typescript
+import { addItem, getCart } from '@spree/next';
+
+export default async function CartPage() {
+  const cart = await getCart();
+
+  async function handleAddItem(formData: FormData) {
+    'use server';
+    await addItem(formData.get('variantId') as string, 1);
+  }
+
+  return <form action={handleAddItem}>...</form>;
+}
+```
+
+## Localization
+
+### Automatic (recommended)
+
+Data functions automatically read locale and country from cookies. Use the included middleware to set cookies based on the URL:
+
+```typescript
+// middleware.ts
+import { createSpreeMiddleware } from '@spree/next/middleware';
+
+export default createSpreeMiddleware({
+  defaultCountry: 'us',
+  defaultLocale: 'en',
+});
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\..*$).*)'],
+};
+```
+
+Then data functions work without any locale arguments:
+
+```typescript
+// Locale/country auto-read from cookies — no options needed
+const products = await listProducts({ limit: 10 });
+const category = await getCategory('clothing/shirts');
+```
+
+Use the `setLocale` server action in country/language switchers:
+
+```typescript
+import { setLocale } from '@spree/next';
+
+await setLocale({ country: 'de', locale: 'de' });
+```
+
+### Manual override
+
+You can still pass locale options explicitly — they override the auto-detected values:
+
+```typescript
+const products = await listProducts({ limit: 10 }, { locale: 'fr', country: 'FR' });
+const category = await getCategory('clothing/shirts', {}, { locale: 'de', country: 'DE' });
+```
+
+## TypeScript
+
+All types are re-exported from `@spree/sdk`:
+
+```typescript
+import type {
+  Product,
+  Order,
+  LineItem,
+  Variant,
+  Category,
+  Country,
+  Currency,
+  Locale,
+  Address,
+  Customer,
+  CreditCard,
+  GiftCard,
+  Fulfillment,
+  DeliveryRate,
+  Payment,
+  PaymentMethod,
+  PaymentSession,
+  PaymentSetupSession,
+  PaginatedResponse,
+  ProductFiltersResponse,
+  AddressParams,
+  SpreeError,
+} from '@spree/next';
+```