title: Core Package purpose: Documentation for @thorprovider/core storefront template description: Next.js storefront template with headless commerce

[App Name]

Next.js 16 storefront with headless commerce. Commerce, auth, i18n, and theming are pre-configured via @thorprovider/* packages — just connect your backend and build features.

🚀 Development Workflow

Step 1: Create the App (Local)

# Minimal
yarn create:app --name my-store

# With backend pre-configured
yarn create:app --name my-store \
  --commerce-provider medusa \
  --commerce-api-url https://your-backend.com \
  --commerce-api-key pk_live_xxx \
  --preset electro \
  --site-url https://my-store.com \
  --generate-regions

cd projects/my-store

This command:

• Clones @thorprovider/core into projects/my-store/
• Installs dependencies
• Generates .env from .env.example (backend flags inject values directly)
• Patches config/site.config.ts with --preset and --site-url if provided
• Optionally runs region generation (--generate-regions) to pre-populate lib/regions-config.ts
• Initializes git with an initial commit
• Generates .v0-context.md (contains frozen architecture files)

Configure your backend (if you didn't use CLI flags):

nano .env
# Set: NEXT_PUBLIC_COMMERCE_API_URL=https://your-backend.com
#      NEXT_PUBLIC_COMMERCE_API_KEY=pk_live_xxx

Test locally:

yarn dev
# → http://localhost:3000

Step 2: Connect to GitHub

1. Create a new repo on GitHub (without README, .gitignore, or license)
2. In your local app directory, add the remote and push:

git remote add origin https://github.com/your-org/your-repo.git
git branch -M main
git push -u origin main

This repository is auto-generated by create:app from @thorprovider/core—it contains frozen architecture files that must not be modified manually. See "Frozen Files" below.

Step 3: Use V0 for Feature Development

1. Copy .v0-context.md (in this repo root) into your first message on v0.app
2. Connect your GitHub repo to V0 (V0 will pull from the remote)
3. Paste the entire .v0-context.md — it tells V0 which files are frozen and which patterns to follow
4. Describe your feature in subsequent messages (e.g., "Add product filters to the product list page")
5. V0 generates code respecting the frozen architecture and @thorprovider/* package constraints
6. Review the PR, merge to main, and deploy to Vercel

Example first message on v0.app:

[Paste full .v0-context.md here]

Now, create a product filter sidebar for the /products page that filters by category and price range.

Step 4: Deploy

After merging changes to main, deployment happens automatically (if you've connected Vercel).

🔒 Frozen Files (Do NOT Modify)

These files define the app's architecture and are frozen by design. V0 respects these; you must too:

| File | Purpose | |------|---------| | lib/commerce.ts | Commerce provider initialization (singleton) | | lib/commerce-provider.tsx | CommerceProvider context wrapper | | lib/region-provider.tsx | RegionProvider context wrapper | | lib/auth-context.tsx | Authentication context | | lib/cart-provider.tsx | CartProvider context wrapper | | lib/storefront-config.ts | Backend-driven storefront config fetch (theme accent, cached) | | lib/region-detection.ts | IP-based region detection from Vercel/Cloudflare geolocation headers | | components/providers/app-providers.tsx | Provider hierarchy (order is critical) | | components/providers/navigation-provider.tsx | NavigationProvider wrapper | | app/layout.tsx | Root layout (ThemeProvider + AppProviders + IP region detection) | | config/site.config.ts | Site configuration (values can change, shape is frozen) |

Why frozen? Changing these breaks the L1–L5 architecture. If you need to modify one, you're likely breaking a constraint. Read docs/rules.md first.

What's Pre-Configured

• Regional commerce (IP-based region detection via Vercel/Cloudflare geolocation headers)
• Shopping cart (persistent, backend-synced via lib/cart-provider.tsx)
• Authentication (JWT via lib/auth-context.tsx)
• Dark mode + CSS token theming + backend-driven accent color override (lib/storefront-config.ts)
• Circuit breaker (auto-fallback when backend is unavailable, auto-resets after 60s)
• Webhook ISR revalidation (app/api/revalidate/route.ts, opt-in via FRONTEND_WEBHOOK_SECRET)
• @thorprovider/components UI library (55 accessible components)

📚 Documentation

For Humans (You)

Read in this order:

1. docs/README.md — Overview + capabilities
2. docs/project-structure.md — Where files live
3. docs/patterns.md — How to write pages, fetch data, style components

For V0 / AI Agents

Copy .v0-context.md to V0's first message. It includes:

• Frozen architecture files (do not modify)
• Type shapes for all domain objects
• Method signatures for all commerce.* calls
• Pre-commit checklist

Then read docs/ in order:

1. docs/project-structure.md
2. docs/dependencies.md — 55 available components
3. docs/types.md — Product, Cart, Order, Customer, Address shapes
4. docs/commerce-api.md — getProducts(), createCart(), etc.
5. docs/patterns.md — Server/client, fetch patterns
6. docs/rules.md — Non-negotiable constraints

Deployment

Vercel: Connect repo → set env vars (NEXT_PUBLIC_COMMERCE_API_URL, NODE_AUTH_TOKEN) → deploy.

Self-hosted: yarn build && yarn start with env vars set in host.

Troubleshooting

Module not found: @thorprovider/* → Verify NODE_AUTH_TOKEN has read:packages scope, then yarn install.

Backend unavailable / circuit breaker → Check NEXT_PUBLIC_COMMERCE_API_URL and network connectivity. Auto-resets after 60s.