@spree/docs 0.1.0

package/dist/developer/storefront/links.md

@@ -0,0 +1,298 @@
+---
+title: "Links"
+sidebarTitle: "Links"
+description: "Learn how to use links for navigation in your Spree Storefront"
+---
+
+Links are used to create navigation throughout the storefront. They can be assigned to [sections](/developer/storefront/sections) and [blocks](/developer/storefront/blocks), enabling users to navigate to different pages, products, categories, or external URLs.
+
+## How Links Work
+
+The `Spree::PageLink` model provides a flexible way to link to various content types:
+
+- **Internal pages** - Link to Pages, Products, Taxons, Posts
+- **External URLs** - Link to any external website
+- **Special links** - Email (`mailto:`) and phone (`tel:`) links
+
+Links are managed through the Page Builder interface, where store staff can select what each link points to.
+
+## Link Model
+
+The [Spree::PageLink](https://github.com/spree/spree/blob/main/core/app/models/spree/page_link.rb) model has these key attributes:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `label` | String | Display text for the link |
+| `url` | String | Custom URL (for external links) |
+| `linkable` | Polymorphic | Reference to internal content (Page, Product, etc.) |
+| `parent` | Polymorphic | Section or Block the link belongs to |
+| `open_in_new_tab` | Boolean | Whether to open in new browser tab |
+| `position` | Integer | Order when multiple links exist |
+
+## Linkable Types
+
+Links can point to various Spree models:
+
+| Linkable Type | Description |
+|---------------|-------------|
+| `Spree::Page` | Internal pages (Home, Shop All, Custom pages) |
+| `Spree::Product` | Product detail pages |
+| `Spree::Taxon` | Category/collection pages |
+| `Spree::Post` | Blog posts |
+| Custom URL | Any external or internal URL |
+
+## Using Links in Sections
+
+### Single Link
+
+For sections that need one link (like a banner):
+
+```ruby app/models/spree/page_sections/promo_banner.rb
+module Spree
+  module PageSections
+    class PromoBanner < Spree::PageSection
+      has_one :link, ->(ps) { ps.links },
+              class_name: 'Spree::PageLink',
+              as: :parent,
+              dependent: :destroy,
+              inverse_of: :parent
+      accepts_nested_attributes_for :link
+
+      def default_links
+        @default_links.presence || [
+          Spree::PageLink.new(label: Spree.t(:shop_now))
+        ]
+      end
+    end
+  end
+end
+```
+
+### Multiple Links
+
+For sections that need multiple links (like navigation):
+
+```ruby app/models/spree/page_sections/footer.rb
+module Spree
+  module PageSections
+    class Footer < Spree::PageSection
+      # Links are provided by Spree::HasPageLinks concern
+      # which is included in Spree::PageSection by default
+
+      def default_links
+        @default_links.presence || [
+          Spree::PageLink.new(label: 'About Us'),
+          Spree::PageLink.new(label: 'Contact'),
+          Spree::PageLink.new(label: 'Privacy Policy')
+        ]
+      end
+    end
+  end
+end
+```
+
+## Using Links in Blocks
+
+Blocks can also have links. Use the `Spree::HasOneLink` concern for single links:
+
+```ruby app/models/spree/page_blocks/cta_button.rb
+module Spree
+  module PageBlocks
+    class CtaButton < Spree::PageBlock
+      include Spree::HasOneLink
+
+      preference :button_style, :string, default: 'primary'
+
+      # Called when the link is deleted
+      def link_destroyed(_link)
+        destroy if page_links_count.zero?
+      end
+    end
+  end
+end
+```
+
+## Accessing Links
+
+```ruby
+# Single link on a section
+section.link
+section.link.label
+section.link.linkable_url
+
+# Multiple links on a section
+section.links
+section.links.each do |link|
+  link.label
+  link.linkable_url
+end
+
+# Link on a block
+block.link
+block.link.label if block.link.present?
+```
+
+## Rendering Links
+
+### Using the Helper
+
+The `page_builder_link_to` helper renders links with Page Builder support:
+
+```erb
+<%# Basic usage %>
+<%= page_builder_link_to section.link %>
+
+<%# With custom label %>
+<%= page_builder_link_to section.link, label: 'Click Here' %>
+
+<%# With CSS class %>
+<%= page_builder_link_to section.link, class: 'btn-primary' %>
+
+<%# Open in new tab %>
+<%= page_builder_link_to section.link,
+    target: (section.link.open_in_new_tab ? '_blank' : nil),
+    rel: (section.link.open_in_new_tab ? 'noopener noreferrer' : nil) %>
+
+<%# With block content %>
+<%= page_builder_link_to section.link do %>
+  <span class="icon">→</span>
+  <%= section.link.label %>
+<% end %>
+```
+
+### Manual Link Rendering
+
+For more control, you can render links manually:
+
+```erb
+<% if section.link.present? %>
+  <%= link_to section.link.linkable_url,
+      target: (section.link.open_in_new_tab ? '_blank' : nil),
+      rel: (section.link.open_in_new_tab ? 'noopener noreferrer' : nil),
+      class: 'btn-primary' do %>
+    <%= section.link.label %>
+  <% end %>
+<% end %>
+```
+
+### Rendering Multiple Links
+
+```erb
+<nav class="footer-links">
+  <% section.links.each do |link| %>
+    <%= page_builder_link_to link, class: 'footer-link' %>
+  <% end %>
+</nav>
+```
+
+## Admin Form for Links
+
+In your section's admin form, render the link editor:
+
+### Single Link
+
+```erb app/views/spree/admin/page_sections/forms/_promo_banner.html.erb
+<%= render 'spree/admin/shared/page_section_image', f: f %>
+
+<div class="py-2">
+  <%= f.fields_for :link do |lf| %>
+    <div class="form-group">
+      <%= lf.label :linkable_type, Spree.t(:link) %>
+      <%= lf.select :linkable_type,
+          @page_section.allowed_linkable_types,
+          { include_blank: false },
+          { class: 'custom-select mb-3', data: { action: 'auto-submit#submit' } } %>
+
+      <div id="linkable_type_dropdown">
+        <%= render 'spree/admin/page_links/linkable_type_dropdown',
+            page_link: lf.object,
+            form_name: 'page_section[link_attributes]' %>
+      </div>
+    </div>
+
+    <div class="custom-control custom-checkbox">
+      <%= lf.check_box :open_in_new_tab,
+          class: 'custom-control-input',
+          data: { action: 'auto-submit#submit' } %>
+      <%= lf.label :open_in_new_tab, class: 'custom-control-label' %>
+    </div>
+  <% end %>
+</div>
+```
+
+## Link URL Resolution
+
+The `linkable_url` method returns the appropriate URL:
+
+```ruby
+link = Spree::PageLink.new(linkable: product)
+link.linkable_url
+# => "/products/red-shirt"
+
+link = Spree::PageLink.new(url: "https://example.com")
+link.linkable_url
+# => "https://example.com"
+
+link = Spree::PageLink.new(url: "example.com")
+link.formatted_url
+# => "http://example.com"  # Adds protocol automatically
+
+link = Spree::PageLink.new(url: "mailto:info@example.com")
+link.formatted_url
+# => "mailto:info@example.com"  # Preserves mailto: protocol
+```
+
+## Creating Links Programmatically
+
+```ruby
+# Link to an internal page
+link = Spree::PageLink.create!(
+  parent: section,
+  label: 'Shop Now',
+  linkable: store.pages.find_by(type: 'Spree::Pages::ShopAll')
+)
+
+# Link to a product
+link = Spree::PageLink.create!(
+  parent: section,
+  label: product.name,
+  linkable: product
+)
+
+# Link to a taxon
+link = Spree::PageLink.create!(
+  parent: section,
+  label: 'New Arrivals',
+  linkable: store.taxons.find_by(name: 'New Arrivals')
+)
+
+# External link
+link = Spree::PageLink.create!(
+  parent: section,
+  label: 'Visit Our Blog',
+  url: 'https://blog.example.com',
+  open_in_new_tab: true
+)
+```
+
+## Automatic Label Setting
+
+When a link's `linkable` is set, the label is automatically populated from the linked resource:
+
+```ruby
+link = Spree::PageLink.new(linkable: product)
+link.valid?
+link.label
+# => "Red T-Shirt" (from product.name)
+```
+
+The label is derived from (in order):
+1. `linkable.title`
+2. `linkable.display_name`
+3. `linkable.name`
+
+## Related Documentation
+
+- [Sections](/developer/storefront/sections) - Adding links to sections
+- [Blocks](/developer/storefront/blocks) - Adding links to blocks
+- [Pages](/developer/storefront/pages) - Understanding internal page linking

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

@@ -0,0 +1,150 @@
+---
+title: Architecture
+description: Server-first architecture, project structure, and auth flow
+---
+
+## Server-First Pattern
+
+The storefront follows a **server-first architecture** where all API calls are made server-side. The Spree API key is never exposed to the browser.
+
+```
+Browser → Server Action → @spree/next → Spree API
+         (with httpOnly cookies)
+```
+
+- **Server Actions** (`src/lib/data/`) — thin wrappers around `@spree/next` data functions
+- **httpOnly Cookies** — auth tokens, cart tokens, and locale are stored securely
+- **No Client-Side API Calls** — the Spree API key stays on the server
+- **Auto-Localization** — locale and country are read from cookies automatically by `@spree/next`
+
+## Project Structure
+
+```
+src/
+├── app/
+│   └── [country]/[locale]/          # Localized routes
+│       ├── (storefront)/            # Main storefront layout
+│       │   ├── page.tsx             # Homepage
+│       │   ├── account/             # Customer account
+│       │   │   ├── addresses/       # Address management
+│       │   │   ├── credit-cards/    # Saved payment methods
+│       │   │   ├── gift-cards/      # Gift cards
+│       │   │   ├── orders/          # Order history
+│       │   │   │   └── [id]/        # Order details
+│       │   │   ├── profile/         # Profile settings
+│       │   │   └── register/        # Registration
+│       │   ├── cart/                # Shopping cart
+│       │   ├── products/            # Product listing
+│       │   │   └── [slug]/          # Product details
+│       │   ├── t/[...permalink]/    # Category pages
+│       │   └── categories/          # Category overview
+│       └── (checkout)/              # Checkout layout (no header/footer)
+│           ├── checkout/[id]/       # Checkout flow
+│           └── order-placed/[id]/   # Order confirmation
+├── components/
+│   ├── cart/                        # CartDrawer
+│   ├── checkout/                    # AddressStep, DeliveryStep, PaymentStep, etc.
+│   ├── layout/                      # Header, Footer, CountrySwitcher
+│   ├── navigation/                  # Breadcrumbs
+│   ├── products/                    # ProductCard, ProductGrid, Filters, MediaGallery, VariantPicker
+│   └── search/                      # SearchBar
+├── contexts/
+│   ├── AuthContext.tsx              # Auth state
+│   ├── CartContext.tsx              # Client-side cart state sync
+│   ├── CheckoutContext.tsx          # Checkout flow state
+│   └── StoreContext.tsx             # Store/locale/currency state
+├── hooks/
+│   ├── useCarouselProducts.ts      # Product carousel data
+│   └── useProductListing.ts        # Product listing with filters
+└── lib/
+    ├── analytics/                   # GTM integration
+    ├── constants.ts                 # App constants
+    ├── data/                        # Server Actions
+    │   ├── addresses.ts             # Address CRUD
+    │   ├── cart.ts                  # Cart operations
+    │   ├── checkout.ts              # Checkout flow
+    │   ├── cookies.ts               # Auth check helper
+    │   ├── countries.ts             # Countries/regions
+    │   ├── credit-cards.ts          # Payment methods
+    │   ├── customer.ts              # Auth & profile
+    │   ├── gift-cards.ts            # Gift cards
+    │   ├── orders.ts                # Order history
+    │   ├── payment.ts               # Payment processing
+    │   ├── products.ts              # Product queries
+    │   ├── store.ts                 # Store configuration
+    │   ├── categories.ts             # Categories
+    │   └── utils.ts                 # Shared helpers (actionResult, withFallback)
+    └── utils/                       # Client utilities
+        ├── address.ts               # Address formatting
+        ├── cookies.ts               # Cookie helpers
+        ├── credit-card.ts           # Card formatting
+        ├── path.ts                  # URL path helpers
+        └── product-query.ts         # Product filter query builder
+```
+
+## Authentication Flow
+
+1. User submits login form
+2. Server action calls `@spree/next` which authenticates with the Spree API
+3. JWT token is stored in an httpOnly cookie by `@spree/next`
+4. Subsequent requests include the token automatically
+5. Token is never accessible to client-side JavaScript
+
+```typescript
+// src/lib/data/customer.ts
+import { login as _login, getCustomer as _getCustomer } from '@spree/next'
+
+export async function login(email: string, password: string) {
+  return _login(email, password) // token stored in httpOnly cookie automatically
+}
+
+export async function getCustomer() {
+  return _getCustomer() // reads token from cookie automatically
+}
+```
+
+## Multi-Region Support
+
+The storefront supports multiple countries and currencies via URL segments:
+
+```
+/us/en/products          # US store, English
+/de/de/products          # German store, German
+/uk/en/products          # UK store, English
+```
+
+A middleware (`src/proxy.ts`) uses `createSpreeMiddleware` from `@spree/next` to detect the visitor's country and locale, then redirects to the correct URL prefix. The `CountrySwitcher` component lets users change regions manually.
+
+## Server Actions
+
+All data fetching is done through server actions in `src/lib/data/`. These are thin wrappers around `@spree/next` functions — locale and currency are resolved automatically from cookies:
+
+```typescript
+// Products
+import { getProducts, getProduct, getProductFilters } from '@/lib/data/products'
+
+const products = await getProducts({ limit: 12 })
+const product = await getProduct('product-slug')
+const filters = await getProductFilters()
+
+// Cart
+import { getCart, addToCart, updateCartItem, removeCartItem } from '@/lib/data/cart'
+
+const cart = await getCart()
+await addToCart('var_xxx', 1)
+await updateCartItem('li_xxx', 2)
+await removeCartItem('li_xxx')
+
+// Authentication
+import { login, register, logout, getCustomer } from '@/lib/data/customer'
+
+await login('user@example.com', 'password')
+const customer = await getCustomer()
+await logout()
+
+// Addresses
+import { getAddresses, createAddress, updateAddress, deleteAddress } from '@/lib/data/addresses'
+
+const addresses = await getAddresses()
+await createAddress({ first_name: 'John', ... })
+```

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

@@ -0,0 +1,141 @@
+---
+title: Customization
+description: Fork, customize, and extend the Spree Next.js Storefront
+---
+
+## Forking the Starter
+
+The recommended approach is to fork the repository so you can customize freely while pulling upstream updates.
+
+### 1. Fork on GitHub
+
+Go to [github.com/spree/storefront](https://github.com/spree/storefront) and click **Fork**.
+
+### 2. Clone Your Fork
+
+```bash
+git clone https://github.com/YOUR_USERNAME/storefront.git
+cd storefront
+npm install
+```
+
+### 3. Add Upstream Remote
+
+```bash
+git remote add upstream https://github.com/spree/storefront.git
+```
+
+### 4. Pull Upstream Updates
+
+When the official starter gets updates, pull them into your fork:
+
+```bash
+git fetch upstream
+git merge upstream/main
+```
+
+Resolve any conflicts in your customized files, then commit.
+
+## Styling
+
+The storefront uses Tailwind CSS 4, which replaces the traditional `tailwind.config.ts` with CSS-native configuration via the `@theme` directive in `src/app/globals.css`.
+
+### Theme Customization
+
+Edit the `@theme inline` block in `src/app/globals.css` to change colors, fonts, and other design tokens:
+
+```css
+@import "tailwindcss";
+
+:root {
+  --background: #fcfaf7;
+  --foreground: #171717;
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: var(--font-geist);
+
+  /* Replace with your brand colors */
+  --color-primary-50: #eff6ff;
+  --color-primary-100: #dbeafe;
+  --color-primary-200: #bfdbfe;
+  --color-primary-300: #93c5fd;
+  --color-primary-400: #60a5fa;
+  --color-primary-500: #0077ff;
+  --color-primary-600: #0066dd;
+  --color-primary-700: #0055bb;
+  --color-primary-800: #004499;
+  --color-primary-900: #003377;
+  --color-primary-950: #001d4d;
+}
+```
+
+Variables defined in `@theme inline` become Tailwind utilities automatically — for example, `--color-primary-500` maps to `bg-primary-500`, `text-primary-500`, etc.
+
+## Components
+
+All components live in `src/components/` and can be customized or replaced:
+
+```
+src/components/
+├── cart/            # CartDrawer
+├── checkout/        # AddressStep, DeliveryStep, PaymentStep, StripePaymentForm, etc.
+├── layout/          # Header, Footer, CountrySwitcher
+├── navigation/      # Breadcrumbs
+├── products/        # ProductCard, ProductGrid, ProductCarousel, Filters, MediaGallery, VariantPicker
+└── search/          # SearchBar
+```
+
+Components use standard React patterns — modify them directly or replace them entirely with your own implementations.
+
+## Data Layer
+
+To customize API behavior, modify the server actions in `src/lib/data/`. Each file handles a specific domain:
+
+| File | Purpose |
+|------|---------|
+| `products.ts` | Product listing and detail queries |
+| `cart.ts` | Cart operations (add, update, remove) |
+| `checkout.ts` | Checkout flow (addresses, shipping, completion) |
+| `customer.ts` | Authentication and profile management |
+| `addresses.ts` | Address CRUD |
+| `orders.ts` | Order history |
+| `payment.ts` | Payment sessions and processing |
+| `categories.ts` | Categories |
+| `countries.ts` | Country and region data |
+| `cookies.ts` | Auth check helper |
+| `store.ts` | Store configuration |
+| `credit-cards.ts` | Saved payment methods |
+| `gift-cards.ts` | Gift card management |
+| `utils.ts` | Shared helpers (error handling, fallbacks) |
+
+These server actions wrap the `@spree/next` package functions. You can add custom logic, caching strategies, or additional transformations as needed.
+
+## Adding New Pages
+
+Follow the existing App Router pattern with localized routes. Place pages under the `(storefront)` route group to inherit the shared header/footer layout:
+
+```
+src/app/[country]/[locale]/(storefront)/your-new-page/page.tsx
+```
+
+```typescript
+import { listProducts } from '@spree/next';
+
+export default async function YourNewPage() {
+  const products = await listProducts({ limit: 6 });
+
+  return (
+    <div>
+      <h1>Your New Page</h1>
+      {/* Your content */}
+    </div>
+  );
+}
+```
+
+## Building a Custom Storefront
+
+If you prefer to build from scratch instead of forking the starter, you can use the `@spree/next` and `@spree/sdk` packages directly in any Next.js application. See the [@spree/next Package](/developer/storefront/nextjs/spree-next-package) documentation for the complete API reference.