@thorprovider/create-thor-app 2.1.0

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.
Files changed (42) hide show
  1. package/README.md +470 -0
  2. package/dist/index.js +1054 -0
  3. package/package.json +46 -0
  4. package/templates/default/.env.example +56 -0
  5. package/templates/default/.eslintrc.json +43 -0
  6. package/templates/default/README.md +151 -0
  7. package/templates/default/app/api/revalidate/route.ts +64 -0
  8. package/templates/default/app/backend-unavailable/page.tsx +85 -0
  9. package/templates/default/app/error.tsx +58 -0
  10. package/templates/default/app/global-error.tsx +208 -0
  11. package/templates/default/app/globals.css +125 -0
  12. package/templates/default/app/layout.tsx +50 -0
  13. package/templates/default/app/not-found.tsx +31 -0
  14. package/templates/default/app/page.tsx +124 -0
  15. package/templates/default/components/providers/app-providers.tsx +77 -0
  16. package/templates/default/components/providers/navigation-provider.tsx +37 -0
  17. package/templates/default/config/site.config.ts +156 -0
  18. package/templates/default/docs/README.md +46 -0
  19. package/templates/default/docs/commerce-api.md +243 -0
  20. package/templates/default/docs/components.md +276 -0
  21. package/templates/default/docs/dependencies.md +53 -0
  22. package/templates/default/docs/patterns.md +100 -0
  23. package/templates/default/docs/project-structure.md +53 -0
  24. package/templates/default/docs/rules.md +51 -0
  25. package/templates/default/docs/types.md +329 -0
  26. package/templates/default/lib/auth-context.tsx +213 -0
  27. package/templates/default/lib/cart-provider.tsx +53 -0
  28. package/templates/default/lib/commerce-provider.tsx +48 -0
  29. package/templates/default/lib/commerce.ts +165 -0
  30. package/templates/default/lib/env.ts +147 -0
  31. package/templates/default/lib/region-detection.ts +80 -0
  32. package/templates/default/lib/region-provider.tsx +53 -0
  33. package/templates/default/lib/regions-config.ts +48 -0
  34. package/templates/default/lib/storefront-config.ts +54 -0
  35. package/templates/default/lib/utils.ts +10 -0
  36. package/templates/default/next-env.d.ts +6 -0
  37. package/templates/default/next.config.mjs +51 -0
  38. package/templates/default/package.json +42 -0
  39. package/templates/default/postcss.config.mjs +8 -0
  40. package/templates/default/proxy.ts +155 -0
  41. package/templates/default/scripts/generate-regions-config.ts +498 -0
  42. package/templates/default/tsconfig.json +43 -0
@@ -0,0 +1,156 @@
1
+ /**
2
+ * Site Configuration Template for @thorprovider/core
3
+ *
4
+ * Generic placeholder values. V0 and starters replace these with brand-specific content.
5
+ * The TYPE SHAPE is what matters — values are meant to be overridden.
6
+ */
7
+
8
+ import type { SiteConfig } from '@thorprovider/types';
9
+
10
+ /**
11
+ * Site configuration — replace values for your brand.
12
+ *
13
+ * ✅ V0 CAN modify: all values below
14
+ * ❌ V0 MUST NOT modify: the `satisfies SiteConfig` type constraint
15
+ */
16
+ export const siteConfig = {
17
+ // Brand Information
18
+ name: 'My Store',
19
+ title: 'My Store | Powered by Thor Commerce',
20
+ description: 'An e-commerce store built with Thor Commerce.',
21
+ tagline: 'Your tagline here',
22
+
23
+ // Logos & Presets
24
+ logo: '/logo.svg',
25
+ logoDark: '/logo-dark.svg',
26
+ preset: 'electro',
27
+
28
+ // Site Metadata
29
+ url: 'https://example.com',
30
+ author: {
31
+ name: 'Store Owner',
32
+ email: 'hello@example.com',
33
+ },
34
+
35
+ // Social Media
36
+ social: {
37
+ twitter: '@mystore',
38
+ instagram: '@mystore',
39
+ facebook: 'mystore',
40
+ },
41
+
42
+ // Navigation
43
+ navigation: [
44
+ { name: 'Home', href: '/' },
45
+ { name: 'Products', href: '/products' },
46
+ ],
47
+
48
+ // Header Navigation Configuration
49
+ header: {
50
+ logo: {
51
+ src: '/logo.svg',
52
+ alt: 'My Store',
53
+ width: 150,
54
+ height: 40,
55
+ href: '/',
56
+ },
57
+ leftLinks: [],
58
+ rightLinks: [
59
+ {
60
+ type: 'preset' as const,
61
+ preset: 'account' as const,
62
+ },
63
+ {
64
+ type: 'preset' as const,
65
+ preset: 'cart' as const,
66
+ },
67
+ ],
68
+ search: {
69
+ enabled: true,
70
+ width: 400,
71
+ placeholder: 'Search products...',
72
+ minChars: 1,
73
+ },
74
+ account: {
75
+ enabled: true,
76
+ label: 'Account',
77
+ icon: { type: 'lucide' as const, name: 'User' },
78
+ items: [
79
+ {
80
+ label: 'Profile',
81
+ href: '/profile',
82
+ icon: { type: 'lucide' as const, name: 'User' },
83
+ },
84
+ {
85
+ label: 'My Orders',
86
+ href: '/orders',
87
+ icon: { type: 'lucide' as const, name: 'Package' },
88
+ },
89
+ {
90
+ divider: true,
91
+ },
92
+ {
93
+ label: 'Logout',
94
+ icon: { type: 'lucide' as const, name: 'LogOut' },
95
+ destructive: true,
96
+ },
97
+ ],
98
+ },
99
+ cart: {
100
+ label: 'Cart',
101
+ variant: 'mini' as const,
102
+ composition: 'compact' as const,
103
+ showBadge: true,
104
+ },
105
+ maxWidth: 1280,
106
+ enableOverflow: true,
107
+ },
108
+
109
+ // Footer Links
110
+ footerLinks: {
111
+ shop: [
112
+ { name: 'All Products', href: '/products' },
113
+ ],
114
+ support: [
115
+ { name: 'Help Center', href: '/help' },
116
+ { name: 'Contact', href: '/contact' },
117
+ ],
118
+ company: [],
119
+ legal: [
120
+ { name: 'Privacy', href: '/legal/privacy' },
121
+ { name: 'Terms', href: '/legal/terms' },
122
+ ],
123
+ },
124
+
125
+ // Copyright
126
+ copyright: {
127
+ year: new Date().getFullYear(),
128
+ text: 'All rights reserved.',
129
+ },
130
+
131
+ // Module Configurations
132
+ modules: {
133
+ cart: {
134
+ mini: {
135
+ variant: 'mini' as const,
136
+ composition: 'compact' as const,
137
+ },
138
+ page: {
139
+ variant: 'page' as const,
140
+ composition: 'full' as const,
141
+ },
142
+ },
143
+ checkout: {
144
+ default: {
145
+ variant: 'complete' as const,
146
+ composition: 'accordion' as const,
147
+ },
148
+ },
149
+ profile: {
150
+ default: {
151
+ variant: 'complete' as const,
152
+ composition: 'tabs' as const,
153
+ },
154
+ },
155
+ },
156
+ } satisfies SiteConfig;
@@ -0,0 +1,46 @@
1
+ # [App Name] — Thor Commerce App
2
+
3
+ Next.js 16 storefront with headless commerce backend. Pre-configured with `@thorprovider/components` UI library and commerce adapters.
4
+
5
+ ## How This Works
6
+
7
+ This app was generated by `create:app` and connects to v0.app for feature development:
8
+
9
+ | Step | Action |
10
+ |------|--------|
11
+ | 1. Created | `create:app` generates this repo with `@thorprovider/*` dependencies pre-installed |
12
+ | 2. Git push | Repo pushed to GitHub |
13
+ | 3. v0.app import | **You (V0) are working here.** This is the app context. |
14
+ | 4. Implement | `@thorprovider/components` if component exists; `components/` if it doesn't |
15
+
16
+ ## Capabilities
17
+
18
+ - ✅ i18n (next-intl, configurable locales)
19
+ - ✅ Regional commerce (IP-based region + currency)
20
+ - ✅ Shopping cart (persistent, synced)
21
+ - ✅ Authentication (JWT)
22
+ - ✅ Responsive (mobile-first, Tailwind 4)
23
+ - ✅ Dark mode + CSS token theming
24
+
25
+ ## Quick Start
26
+
27
+ ```bash
28
+ cp .env.example .env.local && yarn install && yarn dev
29
+ # → http://localhost:3000
30
+ ```
31
+
32
+ ```bash
33
+ NEXT_PUBLIC_COMMERCE_API_URL=https://your-backend.com
34
+ NODE_AUTH_TOKEN=github-pat-with-read:packages-scope
35
+ ```
36
+
37
+ ## Docs Index
38
+
39
+ | File | When to read |
40
+ |------|-------------|
41
+ | `project-structure.md` | Where to create files, folder conventions |
42
+ | `dependencies.md` | What to import from `@thorprovider/*`, component inventory (55 components) |
43
+ | `types.md` | Domain type shapes: Product, Cart, Order, Customer, Address, Money |
44
+ | `commerce-api.md` | All `commerce.*` method signatures + circuit breaker usage |
45
+ | `patterns.md` | Server/client, styling, backend fetch patterns (with code) |
46
+ | `rules.md` | Non-negotiable rules + pre-commit checklist |
@@ -0,0 +1,243 @@
1
+ # Commerce API
2
+
3
+ All backend access goes through `commerce` (from `@/lib/commerce`) + `backendCircuitBreaker` (from `@thorprovider/adapters`).
4
+
5
+ ## Setup (already wired in the app)
6
+
7
+ ```ts
8
+ import { commerce } from '@/lib/commerce';
9
+ import { backendCircuitBreaker } from '@thorprovider/adapters';
10
+ ```
11
+
12
+ **Read operations** — always wrap with circuit breaker:
13
+ ```ts
14
+ const result = await backendCircuitBreaker.execute(() => commerce.method(...), fallback);
15
+ ```
16
+
17
+ **Mutations** — call directly (adapter retries internally):
18
+ ```ts
19
+ const result = await commerce.method(...);
20
+ ```
21
+
22
+ ---
23
+
24
+ ## Storefront Methods
25
+
26
+ ### Products
27
+
28
+ ```ts
29
+ // Get single product by handle (slug)
30
+ commerce.getProduct(handle: string, options?: { regionId?: string }): Promise<Product | undefined>
31
+
32
+ // List products (search, sort, paginate)
33
+ commerce.getProducts(options?: {
34
+ query?: string;
35
+ sortKey?: string; // e.g. 'title', 'price', 'created_at'
36
+ reverse?: boolean;
37
+ first?: number; // limit (default 20)
38
+ skip?: number; // offset
39
+ regionId?: string;
40
+ }): Promise<Product[]>
41
+
42
+ // Recommendations for a product
43
+ commerce.getProductRecommendations(productId: string): Promise<Product[]>
44
+ ```
45
+
46
+ ### Collections
47
+
48
+ ```ts
49
+ commerce.getCollection(handle: string): Promise<Collection | undefined>
50
+ commerce.getCollections(options?: { limit?: number; query?: string }): Promise<Collection[]>
51
+ commerce.getCollectionProducts(handle: string, options?: {
52
+ sortKey?: string; reverse?: boolean; first?: number; after?: string;
53
+ }): Promise<Product[]>
54
+ ```
55
+
56
+ ### Categories
57
+
58
+ ```ts
59
+ commerce.getCategory(idOrHandle: string): Promise<ProductCategory | undefined>
60
+ commerce.getCategories(options?: {
61
+ includeDescendants?: boolean; parentCategoryId?: string;
62
+ limit?: number; query?: string;
63
+ }): Promise<ProductCategory[]>
64
+ commerce.getCategoryProducts(handle: string, options?: {
65
+ sortKey?: string; reverse?: boolean; first?: number;
66
+ }): Promise<Product[]>
67
+ ```
68
+
69
+ ### Cart
70
+
71
+ ```ts
72
+ // Create a new cart
73
+ commerce.createCart(options?: { regionId?: string }): Promise<Cart>
74
+
75
+ // Get existing cart
76
+ commerce.getCart(cartId: string): Promise<Cart | undefined>
77
+
78
+ // Add items (mutation — no circuit breaker)
79
+ commerce.addToCart(cartId: string, lines: Array<{
80
+ merchandiseId: string; // variant ID
81
+ quantity: number;
82
+ }>): Promise<Cart>
83
+
84
+ // Remove items
85
+ commerce.removeFromCart(cartId: string, lineIds: string[]): Promise<Cart>
86
+
87
+ // Update quantities
88
+ commerce.updateCart(cartId: string, lines: Array<{
89
+ id: string; // line item ID
90
+ merchandiseId: string;
91
+ quantity: number;
92
+ }>): Promise<Cart>
93
+ ```
94
+
95
+ ### Checkout
96
+
97
+ ```ts
98
+ // Complete checkout → creates order
99
+ commerce.completeCheckout(cartId: string): Promise<Order>
100
+
101
+ // Shipping
102
+ commerce.getShippingMethods(cartId: string): Promise<ShippingMethod[]>
103
+ commerce.addShippingMethod(cartId: string, methodId: string): Promise<Cart>
104
+
105
+ // Payment
106
+ commerce.getPaymentMethods(options: {
107
+ regionId?: string; cartId?: string; currencyCode?: string;
108
+ }): Promise<PaymentMethod[]>
109
+ commerce.initiatePaymentSession(cartId: string, providerId: string): Promise<void>
110
+
111
+ // Discounts
112
+ commerce.applyDiscountCode(cartId: string, code: string): Promise<Cart>
113
+ commerce.removeDiscountCode(cartId: string, code: string): Promise<Cart>
114
+
115
+ // Address
116
+ commerce.updateBillingAddress?(cartId: string, address: Address): Promise<Cart>
117
+
118
+ // Region data
119
+ commerce.getRegions?(): Promise<Array<{
120
+ id: string; name: string; currency_code: string;
121
+ countries?: Array<{ id: string; iso_2: string; name: string }>;
122
+ }>>
123
+ commerce.getRegionCountries(regionId: string): Promise<Country[]>
124
+ ```
125
+
126
+ ### Auth (via `commerce.auth`)
127
+
128
+ ```ts
129
+ commerce.auth.login({ email, password }): Promise<AuthResponse>
130
+ commerce.auth.register({ email, password, first_name, last_name, phone? }): Promise<AuthResponse>
131
+ commerce.auth.logout(): Promise<void>
132
+ commerce.auth.getCurrentCustomer(): Promise<Customer | null>
133
+ commerce.auth.updateCustomer(data: {
134
+ first_name?: string; last_name?: string; phone?: string; email?: string;
135
+ }): Promise<Customer>
136
+ commerce.auth.isAuthenticated(): Promise<boolean>
137
+ commerce.auth.getAuthToken(): string | null
138
+
139
+ // Password reset
140
+ commerce.auth.requestPasswordReset(email: string): Promise<void>
141
+ commerce.auth.resetPassword(token: string, password: string): Promise<void>
142
+
143
+ // Addresses
144
+ commerce.auth.getAddresses(): Promise<Address[]>
145
+ commerce.auth.createAddress(data: CreateAddressData): Promise<Address>
146
+ commerce.auth.updateAddress(addressId: string, data: Partial<CreateAddressData>): Promise<Address>
147
+ commerce.auth.deleteAddress(addressId: string): Promise<void>
148
+ ```
149
+
150
+ ---
151
+
152
+ ## Admin Methods
153
+
154
+ Admin methods are used in `app/api/admin/` route handlers.
155
+
156
+ ### Orders
157
+
158
+ ```ts
159
+ commerce.getAdminOrders(options?: {
160
+ search?: string;
161
+ status?: string | string[];
162
+ limit?: number; // default 20
163
+ offset?: number;
164
+ order?: string; // sort field
165
+ direction?: 'asc' | 'desc';
166
+ }): Promise<{ orders: Order[]; count: number }>
167
+
168
+ commerce.getAdminOrder?(orderId: string): Promise<Order | undefined>
169
+ commerce.cancelOrder(orderId: string): Promise<Order>
170
+ commerce.createFulfillment(orderId: string, items?: Array<{ id: string; quantity: number }>): Promise<void>
171
+ commerce.createRefund(orderId: string, amount?: number, reason?: string): Promise<void>
172
+ ```
173
+
174
+ ### Products (admin)
175
+
176
+ ```ts
177
+ commerce.getAdminProducts?(options?: {
178
+ query?: string; limit?: number; offset?: number;
179
+ }): Promise<{ products: AdminProduct[]; count: number }>
180
+
181
+ commerce.getAdminProduct?(productId: string): Promise<AdminProduct | undefined>
182
+ ```
183
+
184
+ ### Customers (admin)
185
+
186
+ ```ts
187
+ commerce.getAdminCustomers?(options?: {
188
+ search?: string; limit?: number; offset?: number;
189
+ }): Promise<{ customers: Customer[]; count: number }>
190
+
191
+ commerce.getAdminCustomer?(customerId: string): Promise<Customer | undefined>
192
+ commerce.getAdminCustomerAddresses?(customerId: string): Promise<Address[]>
193
+ commerce.getCustomerOrders?(customerId: string, limit?: number): Promise<Order[]>
194
+ ```
195
+
196
+ ### Inventory
197
+
198
+ ```ts
199
+ commerce.getStockLocations(params?: { salesChannelId?: string }): Promise<StockLocation[]>
200
+ commerce.checkInventoryLevels(variantId: string, salesChannelId?: string): Promise<InventoryLevel[]>
201
+ commerce.validateCartStock(cartId: string): Promise<StockValidation>
202
+ commerce.getFulfillmentOptions(cartId: string, salesChannelId: string): Promise<FulfillmentOption[]>
203
+ ```
204
+
205
+ ---
206
+
207
+ ## Optional Methods (check before calling)
208
+
209
+ Methods marked with `?` may not exist. Always guard:
210
+
211
+ ```ts
212
+ // ✅ Check before calling optional methods
213
+ if (commerce.getAdminOrder) {
214
+ const order = await backendCircuitBreaker.execute(
215
+ () => commerce.getAdminOrder!(orderId),
216
+ null
217
+ );
218
+ }
219
+
220
+ // ❌ Don't call blindly — will throw if not implemented
221
+ const order = await commerce.getAdminOrder(orderId); // might be undefined function
222
+ ```
223
+
224
+ ---
225
+
226
+ ## Circuit Breaker Reference
227
+
228
+ ```ts
229
+ import { backendCircuitBreaker } from '@thorprovider/adapters';
230
+
231
+ // Wrap all READ operations:
232
+ const products = await backendCircuitBreaker.execute(
233
+ () => commerce.getProducts({ first: 20 }),
234
+ [] // fallback shown when backend is down
235
+ );
236
+
237
+ // DO NOT wrap mutations (cart add, checkout, refund, etc.)
238
+ // Adapters handle retry internally for mutations
239
+ ```
240
+
241
+ - **Threshold**: 5 consecutive failures → circuit opens
242
+ - **Reset**: Auto-resets after 60 seconds
243
+ - **Fallback**: Second argument — returned when circuit is OPEN