create-magic-storefront 0.1.2 → 0.1.3
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/package.json
CHANGED
|
@@ -36,7 +36,7 @@ Design from the merchant's data, not from a guess. Read, through `lib/api.ts`:
|
|
|
36
36
|
| What | Why |
|
|
37
37
|
| ------------------------------------------------- | ----------------------------------------------------------------- |
|
|
38
38
|
| `api.shop()`: `name`, `description`, `branding` | Identity: logo, favicon, colors, theme |
|
|
39
|
-
| `api.home()`: the sections in the merchant's order |
|
|
39
|
+
| `api.home()`: the sections in the merchant's order | On a merchant-managed home, what it must hold. A custom home may skip it (`PAGES.md`, Home) |
|
|
40
40
|
| `api.collectionsIndex()`, a few `api.productsIndex()` | Category, price range, how many products, how good the photos are |
|
|
41
41
|
|
|
42
42
|
`shop.branding`:
|
|
@@ -112,9 +112,12 @@ animation, no decorative imagery, no experimental layout. Trust beats taste here
|
|
|
112
112
|
**Account, search, content pages.** Same tokens, quiet layout. Search results reuse the product
|
|
113
113
|
card.
|
|
114
114
|
|
|
115
|
-
**Home** (`app/page.tsx
|
|
116
|
-
|
|
117
|
-
|
|
115
|
+
**Home** (`app/page.tsx`). The one place for a strong visual idea, and the page a design may
|
|
116
|
+
rebuild from scratch: `GET /home` is optional (`PAGES.md`, Home). On a **merchant-managed** home,
|
|
117
|
+
each section type keeps its renderer in `components/sections/`, restyled, in the merchant's order.
|
|
118
|
+
On a **custom** home, compose the layout the design needs from catalog, collection, review and
|
|
119
|
+
content data; merchant sections (banners, stories) may be pulled in as hero imagery where the
|
|
120
|
+
design wants them. Either way every block shows real API data, and an empty read renders nothing.
|
|
118
121
|
|
|
119
122
|
## 4. Telegram Mini App
|
|
120
123
|
|
|
@@ -158,7 +161,8 @@ Before calling a design done, tick every box:
|
|
|
158
161
|
(hero banner or first product image) is not lazy-loaded.
|
|
159
162
|
- [ ] No invented data: prices, badges, ratings, reviews, stock, urgency, customer logos.
|
|
160
163
|
- [ ] Money only through `<Money>` / `formatMoney`.
|
|
161
|
-
- [ ]
|
|
164
|
+
- [ ] Home: merchant-managed — every section type from `api.home()` renders, in the merchant's
|
|
165
|
+
order; custom — every block reads real API data and hides when that read is empty.
|
|
162
166
|
- [ ] Product page: price and add to cart visible without scrolling at 390×844.
|
|
163
167
|
- [ ] Cart and checkout: one column on mobile, labelled fields, errors next to fields, no motion.
|
|
164
168
|
- [ ] Mobile 360px: no horizontal scroll, tap targets ≥ 44px, nothing hover-only.
|
|
@@ -32,7 +32,7 @@ Real data only, from the running shop:
|
|
|
32
32
|
| Page | URL |
|
|
33
33
|
| ---------- | ----------------------------------------------------------------- |
|
|
34
34
|
| Home | `/` |
|
|
35
|
-
| Collection | the first `/collections/…` link in the home page's HTML
|
|
35
|
+
| Collection | the first `/collections/…` link in the home page's HTML or its menu |
|
|
36
36
|
| Product | the first `/products/…` link, plus one sold out or with options if the shop has one |
|
|
37
37
|
| Search | `/search?q=<a word from a product title>` and one with no results |
|
|
38
38
|
| Cart | `/cart` (empty), then again after adding a product |
|
package/template/AGENTS.md
CHANGED
|
@@ -49,18 +49,18 @@ screenshot every page type at 390 and 1280px, fix what you see. Interactive UI f
|
|
|
49
49
|
|
|
50
50
|
## Where things go
|
|
51
51
|
|
|
52
|
-
| Path | What
|
|
53
|
-
| ------------------------------ |
|
|
54
|
-
| `app/` | Pages (server components) and route handlers
|
|
55
|
-
| `app/error.tsx` | Error boundary: the API's `detail`, a retry
|
|
56
|
-
| `app/sitemap.ts` | Sitemap from `GET /sitemap`
|
|
57
|
-
| `app/page.tsx` | Home: renders `GET /home` sections in the merchant's order
|
|
58
|
-
| `components/sections/` | One renderer per home section type; an unknown type renders nothing
|
|
59
|
-
| `components/` | Shared UI; client components start with `'use client'`
|
|
60
|
-
| `lib/api.ts` | The server-side client (`nextCacheFetch`), `orNotFound`
|
|
61
|
-
| `app/providers.tsx` | `MagicStoreProvider`: customer, cart, wishlist, analytics in the browser
|
|
62
|
-
| `app/storefront-api/[...path]` | Same-origin proxy for browser calls without a public storefront token
|
|
63
|
-
| `app/api/magicstore/webhook` | Signed webhook → `revalidateTag`
|
|
52
|
+
| Path | What |
|
|
53
|
+
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
|
|
54
|
+
| `app/` | Pages (server components) and route handlers |
|
|
55
|
+
| `app/error.tsx` | Error boundary: the API's `detail`, a retry |
|
|
56
|
+
| `app/sitemap.ts` | Sitemap from `GET /sitemap` |
|
|
57
|
+
| `app/page.tsx` | Home: renders `GET /home` sections in the merchant's order. Optional: a custom home composes its own (`PAGES.md`) |
|
|
58
|
+
| `components/sections/` | One renderer per home section type; an unknown type renders nothing |
|
|
59
|
+
| `components/` | Shared UI; client components start with `'use client'` |
|
|
60
|
+
| `lib/api.ts` | The server-side client (`nextCacheFetch`), `orNotFound` |
|
|
61
|
+
| `app/providers.tsx` | `MagicStoreProvider`: customer, cart, wishlist, analytics in the browser |
|
|
62
|
+
| `app/storefront-api/[...path]` | Same-origin proxy for browser calls without a public storefront token |
|
|
63
|
+
| `app/api/magicstore/webhook` | Signed webhook → `revalidateTag` |
|
|
64
64
|
|
|
65
65
|
## Commands
|
|
66
66
|
|
package/template/PAGES.md
CHANGED
|
@@ -40,6 +40,24 @@ API's, not the build's. The fetch cache still spares the API.
|
|
|
40
40
|
|
|
41
41
|
## Home — `app/page.tsx`, `components/sections/`
|
|
42
42
|
|
|
43
|
+
The home page belongs to the storefront. `GET /home` is one way to fill it, not a requirement.
|
|
44
|
+
Pick one per project:
|
|
45
|
+
|
|
46
|
+
- **Merchant-managed** (this starter's default): render `GET /home`, described below. The merchant
|
|
47
|
+
arranges the page in the admin and the storefront follows.
|
|
48
|
+
- **Custom**: compose the page yourself from any API data — `productsIndex` with its sorts and
|
|
49
|
+
filters, `collectionsIndex`, `collectionsProducts`, `reviewsSite`, `pagesShow`, `shop.branding` —
|
|
50
|
+
in whatever layout the design calls for. Not calling `api.home()` at all is fine, and so is
|
|
51
|
+
taking only some sections from it (the merchant's `BANNER` slides, the `ANNOUNCEMENT_BAR` text)
|
|
52
|
+
and placing them where the design wants. `components/sections/` can then be deleted.
|
|
53
|
+
|
|
54
|
+
A custom home is a trade-off: the merchant's home editor in the admin no longer controls the page.
|
|
55
|
+
Tell whoever owns the store. Everything else still holds: data only from the API, nothing invented,
|
|
56
|
+
and the page is revalidated by the tags of what it reads (`magicstore:catalog`, `magicstore:shop`),
|
|
57
|
+
not by `HOME_UPDATED` unless it calls `api.home()`.
|
|
58
|
+
|
|
59
|
+
### Rendering `GET /home`
|
|
60
|
+
|
|
43
61
|
`api.home()` answers `{ sections: HomeSection[] }` in the merchant's order. Render each by `type`
|
|
44
62
|
with one component per type; a type the storefront does not know renders **nothing** (the API can
|
|
45
63
|
be newer than the storefront). `GET /theme/section-schema` (`api.themeSectionSchema()`) has the
|
package/template/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
A Next.js (App Router) storefront on the MagicStore Storefront API v2, built only on the public SDK
|
|
4
4
|
(`@magicstoreai/storefront-client`, `@magicstoreai/hydrogen`). The home page from the merchant's
|
|
5
|
-
sections, catalog, collections, search, product with variants, cart, checkout (pickup or delivery,
|
|
5
|
+
sections (or your own composition: `GET /home` is optional), catalog, collections, search, product with variants, cart, checkout (pickup or delivery,
|
|
6
6
|
payment), OTP sign-in and orders, SEO and JSON-LD, and a webhook that revalidates cached pages.
|
|
7
7
|
|
|
8
8
|
```bash
|
package/template/llms.txt
CHANGED
|
@@ -24,15 +24,15 @@ call the client method. `npx create-magic-storefront check` fails on either.
|
|
|
24
24
|
npm create magic-storefront@latest my-shop -- --shop shop.example.uz
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
-
scaffolds a Next.js App Router storefront (home from the merchant's sections, catalog,
|
|
28
|
-
search, cart, checkout, sign-in, orders, SEO, webhook revalidation). Or install the packages:
|
|
27
|
+
scaffolds a Next.js App Router storefront (home from the merchant's sections or your own, catalog,
|
|
28
|
+
product, search, cart, checkout, sign-in, orders, SEO, webhook revalidation). Or install the packages:
|
|
29
29
|
`npm i @magicstoreai/storefront-client @magicstoreai/hydrogen`.
|
|
30
30
|
|
|
31
31
|
## Docs
|
|
32
32
|
|
|
33
33
|
- `PAGES.md` (in a scaffolded storefront; `examples/starter/PAGES.md` in the SDK repository): how to
|
|
34
|
-
build each page type — home from the `/home` sections, collection, product, search,
|
|
35
|
-
checkout, account — with its data calls, cache tags, SEO and required states.
|
|
34
|
+
build each page type — home (from the `/home` sections or custom), collection, product, search,
|
|
35
|
+
cart, checkout, account — with its data calls, cache tags, SEO and required states.
|
|
36
36
|
- [Hydrogen catalogue](node_modules/@magicstoreai/hydrogen/CATALOGUE.md): every export with its props
|
|
37
37
|
or signature, an example, and the API operations it calls. In the SDK repository:
|
|
38
38
|
`packages/hydrogen/CATALOGUE.md`.
|
|
@@ -65,8 +65,10 @@ Public catalog reads need no customer. Render them on the server with a client w
|
|
|
65
65
|
- Lists paginate with `page` + `perPage` (default 24, max 100); read `meta.pagination`, or
|
|
66
66
|
`<Pagination>`. Sorts order (`sort=-createdAt`), filters narrow (`filter[onSale]=true`).
|
|
67
67
|
- A missing value is `null`, never `0` or `""`: show a fallback.
|
|
68
|
-
- The home page is `GET /home
|
|
69
|
-
|
|
68
|
+
- The home page is yours to design. `GET /home` (an ordered list of sections, one `type` each;
|
|
69
|
+
`GET /theme/section-schema` has every type's JSON Schema) is optional: render it to let the
|
|
70
|
+
merchant arrange the page from the admin, or compose a custom home from catalog and content
|
|
71
|
+
data. When you render it, an unknown type renders as nothing.
|
|
70
72
|
|
|
71
73
|
## Credentials in the browser
|
|
72
74
|
|