@thorprovider/create-thor-app 2.1.0 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -159,7 +159,7 @@ function updatePackageJson(opts) {
159
159
  };
160
160
  }
161
161
  delete pkg.scripts?.["generate:agent-index"];
162
- delete pkg.packageManager;
162
+ pkg.packageManager = "yarn@4.5.1";
163
163
  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
164
164
  }
165
165
 
@@ -379,15 +379,15 @@ function createEnvFile(targetDir, overrides) {
379
379
  }
380
380
  function createNpmrc(targetDir) {
381
381
  const npmrcContent = [
382
- "# Thor Commerce packages are published to GitHub Packages.",
383
- "# Set NODE_AUTH_TOKEN in your environment or CI/CD (e.g., Vercel).",
384
- "# Token should be a GitHub PAT (classic) with read:packages.",
385
- "@thorprovider:registry=https://npm.pkg.github.com",
386
- "//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}",
382
+ "# Thor Commerce packages are published to NPM (private, scoped to @thorprovider).",
383
+ "# Set NPM_TOKEN in your environment or CI/CD (e.g., Vercel).",
384
+ "# Token should be an NPM Automation token with read access to @thorprovider org.",
385
+ "@thorprovider:registry=https://registry.npmjs.org",
386
+ "//registry.npmjs.org/:_authToken=${NPM_TOKEN}",
387
387
  ""
388
388
  ].join("\n");
389
389
  writeFileSync2(join4(targetDir, ".npmrc"), npmrcContent);
390
- log(" \u2713 .npmrc created (GitHub Packages)", c.green);
390
+ log(" \u2713 .npmrc created (NPM registry)", c.green);
391
391
  }
392
392
 
393
393
  // src/helpers/site-config.ts
@@ -585,7 +585,7 @@ function generateDeployWorkflow(targetDir) {
585
585
  # VERCEL_TOKEN \u2014 Vercel Access Token
586
586
  # VERCEL_ORG_ID \u2014 From .vercel/project.json (accountId)
587
587
  # VERCEL_PROJECT_ID \u2014 From .vercel/project.json (projectId)
588
- # NODE_AUTH_TOKEN \u2014 GitHub PAT with read:packages (for @thorprovider/*)
588
+ # NPM_TOKEN \u2014 NPM Automation Token with read access to @thorprovider org
589
589
 
590
590
  name: Vercel Deploy
591
591
 
@@ -609,7 +609,7 @@ jobs:
609
609
  uses: actions/setup-node@v4
610
610
  with:
611
611
  node-version: '20'
612
- registry-url: 'https://npm.pkg.github.com'
612
+ registry-url: 'https://registry.npmjs.org'
613
613
 
614
614
  - name: Install Vercel CLI
615
615
  run: npm install -g vercel@latest
@@ -620,7 +620,7 @@ jobs:
620
620
  - name: Build Project
621
621
  run: vercel build \${{ github.ref == 'refs/heads/main' && '--prod' || '' }} --token=\${{ secrets.VERCEL_TOKEN }}
622
622
  env:
623
- NODE_AUTH_TOKEN: \${{ secrets.NODE_AUTH_TOKEN }}
623
+ NPM_TOKEN: \${{ secrets.NPM_TOKEN }}
624
624
 
625
625
  - name: Deploy to Vercel
626
626
  id: deploy
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@thorprovider/create-thor-app",
3
- "version": "2.1.0",
3
+ "version": "3.0.1",
4
4
  "description": "CLI to scaffold a new Thor Commerce application from @thorprovider/core template",
5
5
  "type": "module",
6
6
  "bin": "./dist/index.js",
@@ -1,3 +1,9 @@
1
+ ---
2
+ title: Core Package
3
+ purpose: Documentation for @thorprovider/core storefront template
4
+ description: Next.js storefront template with headless commerce
5
+ ---
6
+
1
7
  # [App Name]
2
8
 
3
9
  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.
@@ -92,10 +98,11 @@ These files define the app's architecture and are **frozen by design**. V0 respe
92
98
  | `lib/region-provider.tsx` | RegionProvider context wrapper |
93
99
  | `lib/auth-context.tsx` | Authentication context |
94
100
  | `lib/cart-provider.tsx` | CartProvider context wrapper |
101
+ | `lib/storefront-config.ts` | Backend-driven storefront config fetch (theme accent, cached) |
102
+ | `lib/region-detection.ts` | IP-based region detection from Vercel/Cloudflare geolocation headers |
95
103
  | `components/providers/app-providers.tsx` | Provider hierarchy (order is critical) |
96
104
  | `components/providers/navigation-provider.tsx` | NavigationProvider wrapper |
97
- | `app/[locale]/layout.tsx` | Root layout (passes `initialRegionId` to AppProviders) |
98
- | `src/i18n/routing.ts` | i18n routing config |
105
+ | `app/layout.tsx` | Root layout (ThemeProvider + AppProviders + IP region detection) |
99
106
  | `config/site.config.ts` | Site configuration (values can change, shape is frozen) |
100
107
 
101
108
  **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.
@@ -104,13 +111,12 @@ These files define the app's architecture and are **frozen by design**. V0 respe
104
111
 
105
112
  ## What's Pre-Configured
106
113
 
107
- - i18n via next-intl (add locales in `src/i18n/routing.ts` + `messages/`)
108
- - Regional commerce (IP-based region + currency detection)
109
- - **V0 Note:** Region config (`lib/regions-config.ts`) uses relative imports for v0 preview compatibility. Never change imports to bare paths.
110
- - Shopping cart (persistent, backend-synced)
111
- - Authentication (JWT)
112
- - Dark mode + CSS token theming
113
- - Circuit breaker (auto-fallback when backend is unavailable)
114
+ - Regional commerce (IP-based region detection via Vercel/Cloudflare geolocation headers)
115
+ - Shopping cart (persistent, backend-synced via `lib/cart-provider.tsx`)
116
+ - Authentication (JWT via `lib/auth-context.tsx`)
117
+ - Dark mode + CSS token theming + backend-driven accent color override (`lib/storefront-config.ts`)
118
+ - Circuit breaker (auto-fallback when backend is unavailable, auto-resets after 60s)
119
+ - Webhook ISR revalidation (`app/api/revalidate/route.ts`, opt-in via `FRONTEND_WEBHOOK_SECRET`)
114
120
  - `@thorprovider/components` UI library (55 accessible components)
115
121
 
116
122
  ## 📚 Documentation
@@ -1,9 +1,9 @@
1
1
  'use client'
2
2
 
3
3
  /**
4
- * Locale-Level Error Boundary
4
+ * Error Boundary
5
5
  *
6
- * Catches errors thrown inside app/[locale]/layout.tsx provider chain
6
+ * Catches errors thrown inside app/layout.tsx provider chain
7
7
  * (RegionProvider, AuthProvider, CartProvider failures).
8
8
  *
9
9
  * Self-contained — does not import from @/components/ so it can render
@@ -1,7 +1,7 @@
1
1
  /**
2
- * Locale-Level Not Found Page
2
+ * Not Found Page
3
3
  *
4
- * Displayed when a page inside app/[locale]/ does not exist.
4
+ * Displayed when a requested page does not exist.
5
5
  * Self-contained — does not import @thorprovider/components components.
6
6
  * Projects replace this with a branded 404 page.
7
7
  */
@@ -15,12 +15,12 @@ This app was generated by `create:app` and connects to v0.app for feature develo
15
15
 
16
16
  ## Capabilities
17
17
 
18
- - ✅ i18n (next-intl, configurable locales)
19
- - ✅ Regional commerce (IP-based region + currency)
20
- - ✅ Shopping cart (persistent, synced)
18
+ - ✅ Regional commerce (IP-based region + currency detection)
19
+ - ✅ Shopping cart (persistent, backend-synced)
21
20
  - ✅ Authentication (JWT)
22
21
  - ✅ Responsive (mobile-first, Tailwind 4)
23
- - ✅ Dark mode + CSS token theming
22
+ - ✅ Dark mode + CSS token theming + backend-driven accent color override
23
+ - ✅ Webhook ISR revalidation (opt-in via `FRONTEND_WEBHOOK_SECRET`)
24
24
 
25
25
  ## Quick Start
26
26
 
@@ -108,7 +108,7 @@ Standard UI primitives. All follow shadcn patterns.
108
108
  Components receive data via props from server components. Example:
109
109
 
110
110
  ```tsx
111
- // app/[locale]/page.tsx (server component)
111
+ // app/page.tsx (server component)
112
112
  import { commerce } from '@/lib/commerce';
113
113
  import { backendCircuitBreaker } from '@thorprovider/adapters';
114
114
  import { ProductCard } from '@thorprovider/components';
@@ -32,12 +32,14 @@ Need a component?
32
32
 
33
33
  ## @thorprovider/providers — Available Hooks
34
34
 
35
+ The app exposes hooks via local wrappers in `lib/`. **Always import from `@/lib/*`** (not from `@thorprovider/providers` directly) — the wrappers inject the correct commerce/region/auth dependencies:
36
+
35
37
  ```ts
36
- import { useCart } from '@thorprovider/providers'; // items, total, addToCart()
37
- import { useAuth } from '@thorprovider/providers'; // user, login(), logout()
38
- import { useRegion } from '@thorprovider/providers'; // current region + currency
39
- import { useNavigation } from '@thorprovider/providers'; // Link, Image (framework-agnostic)
40
- import { useCommerce } from '@thorprovider/providers'; // commerce provider instance
38
+ import { useCart } from '@/lib/cart-provider'; // cart, items, addItem(), removeItem(), updateQuantity()
39
+ import { useAuth } from '@/lib/auth-context'; // customer, isAuthenticated, login(), logout()
40
+ import { useRegion } from '@/lib/region-provider'; // region, regions, setRegion()
41
+ import { useCommerce } from '@/lib/commerce-provider'; // provider (commerce instance)
42
+ import { useNavigation } from '@thorprovider/providers'; // Link, navigate() (framework-agnostic)
41
43
  ```
42
44
 
43
45
  ## Commerce API + Types
@@ -3,7 +3,7 @@
3
3
  ## 1. Server Page (Data Fetch)
4
4
 
5
5
  ```tsx
6
- // app/[locale]/products/page.tsx
6
+ // app/products/page.tsx
7
7
  import { backendCircuitBreaker } from '@thorprovider/adapters';
8
8
  import { commerce } from '@/lib/commerce';
9
9
 
@@ -85,16 +85,41 @@ export async function GET() {
85
85
 
86
86
  ---
87
87
 
88
- ## 5. Admin Route
88
+ ## 5. Storefront Config (Theme Accent)
89
+
90
+ `lib/storefront-config.ts` is called automatically in `app/layout.tsx` to apply a backend-driven accent color override. You can also read it in any server component:
89
91
 
90
92
  ```ts
91
- // app/api/admin/orders/route.ts
92
- import { adminFetch } from '@/lib/admin/utils/admin-fetch';
93
+ // app/some-page/page.tsx
94
+ import { getStorefrontConfig } from '@/lib/storefront-config';
93
95
 
94
- export async function GET() {
95
- const res = await adminFetch('/api/admin/orders?limit=20');
96
- return Response.json(await res.json());
96
+ export default async function SomePage() {
97
+ const config = await getStorefrontConfig(); // null if backend unreachable or not configured
98
+ const accentColor = config?.themeAccentColor; // e.g. "indigo", "blue", or custom oklch value
99
+ // ...
97
100
  }
98
101
  ```
99
102
 
100
- ❌ Never `fetch('/api/admin/...')` directly — `adminFetch` handles credentials + 3x retry.
103
+ - Returns `null` gracefully when the backend is unreachable or the provider does not implement `getStorefrontConfig`.
104
+ - Result is cached per React server request (deduped across components in the same render).
105
+
106
+ ---
107
+
108
+ ## 6. Webhook ISR Revalidation
109
+
110
+ The app ships with a webhook endpoint at `app/api/revalidate/route.ts`. Enable it by setting `FRONTEND_WEBHOOK_SECRET` in `.env`:
111
+
112
+ ```bash
113
+ FRONTEND_WEBHOOK_SECRET=your-shared-secret
114
+ ```
115
+
116
+ The backend plugin sends `POST /api/revalidate` with `x-webhook-secret` header. Supported events:
117
+
118
+ | Event | Effect |
119
+ |-------|--------|
120
+ | `site_config.updated` | Revalidates `site-config` cache tag |
121
+ | `storefront_config.updated` | Revalidates `storefront-config` cache tag |
122
+ | `sales_channel.updated` | Revalidates both tags |
123
+ | _(any other)_ | Revalidates both tags as a safety net |
124
+
125
+ ❌ Never expose `FRONTEND_WEBHOOK_SECRET` in client-side code — it is a server-only env var.
@@ -4,42 +4,50 @@
4
4
 
5
5
  ```
6
6
  app/
7
- [locale]/
8
- layout.tsx ← Provider chain (frozen — never reorder)
9
- page.tsx ← Home page
10
- products/ ← Add your feature pages here
11
- api/ ← API routes (server-side only)
7
+ layout.tsx ← Root layout: ThemeProvider + AppProviders + IP region detection (frozen)
8
+ page.tsx ← Placeholder home page (replace with your content)
9
+ error.tsx ← Error boundary for provider/route failures
10
+ global-error.tsx ← Global error boundary (catches root layout crashes, env var errors)
11
+ not-found.tsx ← 404 page
12
+ globals.css ← Global styles
13
+ products/ ← Add your feature pages here
14
+ api/
15
+ revalidate/
16
+ route.ts ← Webhook ISR revalidation endpoint (opt-in)
17
+ backend-unavailable/
18
+ page.tsx ← Shown by proxy.ts when backend is unreachable
12
19
 
13
- components/ ← Your page-specific components
20
+ components/ ← Your page-specific components
14
21
  providers/
15
- app-providers.tsx ← Provider chain composite (frozen)
22
+ app-providers.tsx ← Provider chain composite (frozen — never reorder)
23
+ navigation-provider.tsx ← ClientNavigationProvider wrapper
16
24
 
17
25
  config/
18
- site.config.ts ← Brand: name, logo, navigation, color preset
26
+ site.config.ts ← Brand: name, logo, navigation, color preset
19
27
 
20
- lib/ ← Infrastructure (don't edit unless adding utilities)
21
- commerce.ts ← Backend connection
22
- auth-context.tsx ← Auth provider
23
- cart-provider.tsx ← Cart provider
24
-
25
- messages/ ← i18n translation files
26
- en.json
27
- es.json
28
-
29
- src/i18n/
30
- routing.ts ← Locale list (add new locales here)
28
+ lib/ ← Infrastructure (frozen unless adding utilities)
29
+ commerce.ts ← Commerce singleton (createProvider, lazy proxy)
30
+ commerce-provider.tsx ← ClientCommerceProvider + useCommerce hook
31
+ region-provider.tsx ← ClientRegionProvider + useRegion hook
32
+ auth-context.tsx ← AuthProvider + useAuth hook
33
+ cart-provider.tsx ← ClientCartProvider + useCart hook
34
+ storefront-config.ts ← Backend-driven storefront config fetch (theme accent, cached)
35
+ region-detection.ts ← IP-based region detection from Vercel/Cloudflare headers
36
+ regions-config.ts ← Auto-generated locale→region map (do NOT edit manually)
37
+ env.ts ← Zod-validated environment variable schema
38
+ utils.ts ← cn() class merging helper
31
39
  ```
32
40
 
33
41
  ## Where Does X Go?
34
42
 
35
43
  | Task | Location |
36
44
  |------|----------|
37
- | New page | `app/[locale]/[slug]/page.tsx` |
45
+ | New page | `app/[slug]/page.tsx` |
38
46
  | Page-specific component | `components/[feature].tsx` |
39
47
  | Reusable UI primitive | `@thorprovider/components` first (see `dependencies.md`) |
40
48
  | Site name, logo, nav links | `config/site.config.ts` |
41
- | New language | `messages/[locale].json` + `src/i18n/routing.ts` |
42
49
  | API route | `app/api/[route]/route.ts` |
50
+ | Environment variables | `.env` (copy from `.env.example`) |
43
51
 
44
52
  ## Component Decision
45
53
 
@@ -51,3 +59,13 @@ Need a UI component?
51
59
  ```
52
60
 
53
61
  → See `dependencies.md` for full `@thorprovider/components` inventory.
62
+
63
+ ## Auto-Generated Files
64
+
65
+ `lib/regions-config.ts` is generated automatically on `dev` and `build` via the `predev`/`prebuild` scripts.
66
+
67
+ ```bash
68
+ yarn generate:regions # regenerate manually
69
+ ```
70
+
71
+ **Never edit `lib/regions-config.ts` by hand** — it will be overwritten on the next build.
@@ -1,6 +1,6 @@
1
1
  # Rules
2
2
 
3
- These rules protect the app's ability to: swap backends without code changes, work in dark mode, survive backend downtime, stay framework-portable, and work in v0 previews.
3
+ These rules protect the app's ability to: swap backends without code changes, work in dark mode, survive backend downtime, and stay framework-portable.
4
4
 
5
5
  ## Non-Negotiables
6
6
 
@@ -10,32 +10,39 @@ These rules protect the app's ability to: swap backends without code changes, wo
10
10
  | No raw `fetch(COMMERCE_API_URL + '...')` | Raw URLs bypass the adapter layer | No retry, credential leak, lock-in |
11
11
  | No `import Link from 'next/link'` in `components/` | Components must be framework-portable | Breaks portability; use `useNavigation()` |
12
12
  | Wrap reads in `backendCircuitBreaker.execute(fn, fallback)` | Backend can be intermittently unavailable | Page crashes instead of showing fallback |
13
- | Use `adminFetch()` for admin API routes | Handles credentials + 3x retry automatically | One transient failure breaks admin panel |
14
13
  | No `#hex` / `rgb()` inline colors | CSS tokens enable dark mode + theming | Dark mode breaks; theme non-customizable |
15
14
  | Don't re-implement `@thorprovider/components` components | 55 exist with full TypeScript + accessibility | Duplicate code, inconsistent UI — see `dependencies.md` for full list |
16
- | Use relative imports for `lib/` files (never bare paths) | v0 bundler only resolves relative imports | V0 preview fails with "Unable to resolve specifier" error |
17
15
 
18
16
  ## Provider Chain (Frozen Order)
19
17
 
18
+ Root layout (`app/layout.tsx`) wraps the full tree with `ThemeProvider`, then delegates to `AppProviders`:
19
+
20
+ ```tsx
21
+ // app/layout.tsx
22
+ <ThemeProvider preset={siteConfig.preset}>
23
+ <AppProviders initialRegionId={initialRegionId}>
24
+ {children}
25
+ </AppProviders>
26
+ </ThemeProvider>
27
+ ```
28
+
20
29
  **File:** `components/providers/app-providers.tsx`
21
30
 
22
31
  ```tsx
23
- <NextIntlClientProvider>
24
- <ClientCommerceProvider>
25
- <ClientRegionProvider>
26
- <AuthProvider>
27
- <ClientCartProvider>
28
- <ClientNavigationProvider>
29
- {children}
30
- </ClientNavigationProvider>
31
- </ClientCartProvider>
32
- </AuthProvider>
33
- </ClientRegionProvider>
34
- </ClientCommerceProvider>
35
- </NextIntlClientProvider>
32
+ <ClientCommerceProvider>
33
+ <ClientRegionProvider initialRegionId={initialRegionId}>
34
+ <AuthProvider>
35
+ <ClientCartProvider>
36
+ <ClientNavigationProvider>
37
+ {children}
38
+ </ClientNavigationProvider>
39
+ </ClientCartProvider>
40
+ </AuthProvider>
41
+ </ClientRegionProvider>
42
+ </ClientCommerceProvider>
36
43
  ```
37
44
 
38
- Each provider requires the context of the prior one. Reordering = runtime crash.
45
+ Each provider depends on the context of the prior one. Reordering = runtime crash.
39
46
  To add a custom provider → wrap `{children}` **inside** `ClientNavigationProvider`.
40
47
 
41
48
  ## Pre-Commit Checklist
@@ -43,7 +50,7 @@ To add a custom provider → wrap `{children}` **inside** `ClientNavigationProvi
43
50
  - [ ] Checked `@thorprovider/components` inventory before creating a new UI component?
44
51
  - [ ] All `commerce.get*()` reads wrapped in `backendCircuitBreaker.execute(fn, fallback)`?
45
52
  - [ ] No backend SDK imports (`@meduzajs/js-sdk`, `@shopify/api`, etc.)?
46
- - [ ] No raw `fetch(COMMERCE_API_URL...)` or bare admin `fetch()`?
53
+ - [ ] No raw `fetch(COMMERCE_API_URL...)` calls?
47
54
  - [ ] No `import Link/Image from 'next/*'` inside `components/`?
48
55
  - [ ] No hardcoded `#hex`, `rgb()`, or Tailwind arbitrary non-token colors?
49
56
  - [ ] `yarn type-check` passes?
@@ -3,7 +3,7 @@
3
3
  *
4
4
  * V0: COPY THIS FILE VERBATIM when creating starters or apps.
5
5
  * This is the ONLY place where createProvider() should be called.
6
- * NEVER call createProvider() in app/[locale]/layout.tsx or elsewhere.
6
+ * NEVER call createProvider() in app/layout.tsx or elsewhere.
7
7
  * See: .v0/docs/v0_provider_chain.md
8
8
  *
9
9
  * This file initializes the commerce provider for Thor Commerce starters.
@@ -5,16 +5,9 @@
5
5
  * Supports Vercel (`x-vercel-ip-country`) and Cloudflare (`cf-ipcountry`).
6
6
  *
7
7
  * Uses auto-generated regions-config (from `yarn generate:regions`) as the
8
- * source of truth for locale→region mapping.
9
- *
10
- * **Important: Import paths matter**
11
- * The generated file at `lib/regions-config.ts` uses RELATIVE imports (./regions-config)
12
- * not bare paths like '../src/generated/...'. This is critical for V0 compatibility:
13
- * - V0's bundler sandbox cannot resolve bare path imports
14
- * - Only relative imports (../, ./) and node_modules work in V0's ESBuild bundler
15
- * - Local bundlers (Turbopack, webpack) handle bare paths, but V0 is stricter
16
- *
17
- * If you move this file or change imports, always use relative paths!
8
+ * source of truth for locale→region mapping. The generated file lives at
9
+ * lib/regions-config.ts (same directory) so that relative imports work in
10
+ * all environments, including v0's preview sandbox.
18
11
  */
19
12
 
20
13
  import { headers } from 'next/headers';
@@ -13,10 +13,10 @@
13
13
  "generate:agent-index": "node ../../scripts/generate-core-agents-index.cjs"
14
14
  },
15
15
  "dependencies": {
16
- "@thorprovider/adapters": "^3.0.2",
17
- "@thorprovider/components": "^1.0.2",
18
- "@thorprovider/providers": "^1.0.2",
19
- "@thorprovider/types": "^2.0.2",
16
+ "@thorprovider/adapters": "^4.0.0",
17
+ "@thorprovider/components": "^2.0.0",
18
+ "@thorprovider/providers": "^2.0.0",
19
+ "@thorprovider/types": "^3.0.0",
20
20
  "clsx": "^2.1.1",
21
21
  "next": "16.0.10",
22
22
  "react": "19.2.0",