> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Storefront Template — SaaS Tool

> A premium dark-theme Next.js storefront template designed for selling subscription-based digital tools. Forkable, AI-customizable, and wired to Shoppex checkout.

The SaaS-Tool Storefront Template is a forkable Next.js storefront built for merchants selling **subscription-based digital products** — license-based software, automation tools, Discord-bot SaaS, cheats. It is opinionated where the [Storefront Starter](/headless/storefront-starter) is generic.

<Info>
  Use this template when your catalog is mostly digital subscriptions with multiple plan tiers per product. Use the Storefront Starter when you want a more neutral baseline that fits any vertical.
</Info>

## Create a Storefront

```bash theme={"system"}
bunx create-shoppex-storefront my-tool-shop --template saas-tool
cd my-tool-shop
bun install
bun run dev
```

For non-interactive setup:

```bash theme={"system"}
bunx create-shoppex-storefront my-tool-shop \
  --template saas-tool \
  --shop-slug your-shop \
  --customer-portal-url https://account.yourdomain.com
```

The dev server runs on [http://localhost:3013](http://localhost:3013) and ships in **demo mode** by default — sample products, sample reviews, demo checkout — so you can rebrand before connecting to your live shop.

## What Is Included

<CardGroup cols={2}>
  <Card title="Hero with Background Art" icon="image">
    Full-bleed hero image slot, gradient text headline, floating pill nav with scroll-aware shrink animation.
  </Card>

  <Card title="Products Carousel" icon="grid-2">
    Drag-to-scroll Embla carousel with hover-sharpen image effect, status badges per tool, and a search/sort grid on the dedicated `/products` page.
  </Card>

  <Card title="Detail Page with 3-Plan Selector" icon="list-check">
    Per-product page with video slot, system requirements grid, 3-card subscription selector with "Most Popular" highlight, and a modal checkout.
  </Card>

  <Card title="Reviews + Features + FAQ" icon="messages">
    Per-product customer reviews, "What you get" feature list with sub-feature counts, and an accordion FAQ. Six-card "Why choose us" on the home page.
  </Card>

  <Card title="Status Page" icon="signal">
    Live-style server status with uptime bars and per-product detection + version state.
  </Card>

  <Card title="Free-Tool Landing" icon="download">
    A "free spoofer" or free-tier tool landing page wired in by default — easy to delete or repurpose.
  </Card>
</CardGroup>

## AI-First Customization

Two config files cover \~80% of customizations. AI agents (Claude, Codex, Cursor) can edit them by following the [`CLAUDE.md`](https://github.com/ShoppexIO/storefront-template-saas-tool/blob/main/CLAUDE.md) operating manual at the repo root.

<Steps>
  <Step title="Brand identity">
    Edit [`theme.config.ts`](https://github.com/ShoppexIO/storefront-template-saas-tool/blob/main/theme.config.ts) — brand name, accent color, hero copy, footer columns, social links.
  </Step>

  <Step title="Catalog and content">
    Edit [`src/config/storefront.config.ts`](https://github.com/ShoppexIO/storefront-template-saas-tool/blob/main/src/config/storefront.config.ts) — products, plans, status reports, reviews, features, jobs, FAQ.
  </Step>

  <Step title="Use a recipe">
    Pick a step-by-step recipe from `docs/recipes/` (rebrand, change plan periods, add a category, customize status vocab, swap reviews, edit hero text, customize checkout fields, connect Shoppex checkout).
  </Step>

  <Step title="Or use a prompt">
    Pick a prompt template from `docs/prompts/` and paste it into your AI agent. The recipes and prompts are linked from each other.
  </Step>
</Steps>

## Connect to Live Shoppex

The modal checkout is wired to `@shoppexio/storefront`. Demo mode shows a confirmation toast; live mode creates a real invoice and redirects to hosted checkout.

<Steps>
  <Step title="Switch off demo mode">
    In `.env.local`:

    ```
    NEXT_PUBLIC_SHOPPEX_SHOP_SLUG=<your-shop>
    NEXT_PUBLIC_SHOPPEX_USE_SAMPLE_DATA=false
    ```
  </Step>

  <Step title="Map plans to Shoppex products">
    For each plan in `storefront.config.ts`, set `productId` and optionally `variantId` so the checkout SDK knows which Shoppex product to invoice.
  </Step>

  <Step title="Verify">
    Click Purchase Now on any product, fill in your email, accept terms — the browser redirects to `checkout.shoppex.io/invoice/<id>`. The hosted checkout handles payment, webhooks, and license delivery.
  </Step>
</Steps>

## Stack

* Next.js 16 (App Router, RSC)
* TypeScript strict
* Tailwind CSS v4 + hand-rolled BEM-style CSS
* Radix UI primitives, Lucide icons, Embla carousel
* `@shoppexio/storefront` for catalog reads + checkout

## Differences vs. the Engine Starter

|                | Engine Starter               | SaaS-Tool Template                                  |
| -------------- | ---------------------------- | --------------------------------------------------- |
| **Vertical**   | Generic                      | Subscription-based digital tools                    |
| **Theme**      | Light, clean                 | Dark, premium, cinematic                            |
| **Hero**       | Headline + CTA               | Full-bleed background art + gradient headline       |
| **Plans**      | Single price per product     | 3-card subscription selector                        |
| **Pages**      | Home, products, detail, jobs | + Status, free-tool landing, FAQ, payment methods   |
| **AI anchors** | Standard                     | CLAUDE.md, AGENTS.md, 8 recipes, 4 prompt templates |

If neither template fits, fork the closer one and edit. Both are MIT-licensed.