@shoppexio/storefront-react 0.1.0 → 0.1.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/CHANGELOG.md +5 -0
- package/README.md +149 -71
- package/package.json +12 -8
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.1
|
|
4
|
+
|
|
5
|
+
- README rewritten for theme developers: install, quick start, theming,
|
|
6
|
+
eject and links. Package metadata: support contact and keywords.
|
|
7
|
+
|
|
3
8
|
## 0.1.0
|
|
4
9
|
|
|
5
10
|
- First release. The commerce layer of the Shoppex code templates (SDK access,
|
package/README.md
CHANGED
|
@@ -1,22 +1,151 @@
|
|
|
1
1
|
# @shoppexio/storefront-react
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
the
|
|
6
|
-
|
|
3
|
+
React hooks, models and a ready-made customer account for Shoppex code
|
|
4
|
+
storefronts. A code storefront is a shop front you write yourself in React and
|
|
5
|
+
Vite; Shoppex builds it, serves it on the shop's domain and runs checkout. This
|
|
6
|
+
package handles the commerce part (catalog, product pages, cart, reviews, the
|
|
7
|
+
signed-in customer area), so your code is the design.
|
|
7
8
|
|
|
8
|
-
|
|
9
|
-
runs: `window.shoppex` (the Storefront SDK, loaded as a CDN script by your
|
|
10
|
-
`index.html`) and `window.__SHOPPEX_INITIAL__` (the shop, the catalog, the
|
|
11
|
-
merchant's saved content). It never bundles the SDK.
|
|
9
|
+
## Install
|
|
12
10
|
|
|
13
11
|
```sh
|
|
12
|
+
npm install @shoppexio/storefront-react
|
|
14
13
|
bun add @shoppexio/storefront-react
|
|
14
|
+
pnpm add @shoppexio/storefront-react
|
|
15
15
|
```
|
|
16
16
|
|
|
17
17
|
Peer dependencies: `react` and `react-dom` 19.2, `react-router-dom` 7.18.
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
The package reads what Shoppex puts on the page before your bundle runs: the
|
|
20
|
+
Storefront SDK as `window.shoppex` (a script tag in your `index.html`) and the
|
|
21
|
+
shop's catalog and settings as `window.__SHOPPEX_INITIAL__`. It does not bundle
|
|
22
|
+
the SDK, and it throws a clear error when either is missing.
|
|
23
|
+
|
|
24
|
+
## Quick start
|
|
25
|
+
|
|
26
|
+
```tsx
|
|
27
|
+
// main.tsx
|
|
28
|
+
import { createRoot } from 'react-dom/client';
|
|
29
|
+
import { BrowserRouter, Route, Routes } from 'react-router-dom';
|
|
30
|
+
import {
|
|
31
|
+
ACCOUNT_PATH,
|
|
32
|
+
CartProvider,
|
|
33
|
+
formatMoney,
|
|
34
|
+
readStorefrontData,
|
|
35
|
+
StorefrontProvider,
|
|
36
|
+
useCart,
|
|
37
|
+
useStorefront,
|
|
38
|
+
} from '@shoppexio/storefront-react';
|
|
39
|
+
import { AccountPage } from '@shoppexio/storefront-react/account';
|
|
40
|
+
import '@shoppexio/storefront-react/account.css';
|
|
41
|
+
|
|
42
|
+
function Shelf() {
|
|
43
|
+
const { catalog } = useStorefront();
|
|
44
|
+
const { add, count, busy } = useCart();
|
|
45
|
+
return (
|
|
46
|
+
<main>
|
|
47
|
+
<p>{count} in cart</p>
|
|
48
|
+
{catalog.products.map((product) => (
|
|
49
|
+
<button
|
|
50
|
+
key={product.id}
|
|
51
|
+
disabled={busy}
|
|
52
|
+
onClick={() => add(product, product.priceVariants[0] ?? null, product.quantityMin)}
|
|
53
|
+
>
|
|
54
|
+
{product.name}, {formatMoney(product.price, product.currency)}
|
|
55
|
+
</button>
|
|
56
|
+
))}
|
|
57
|
+
</main>
|
|
58
|
+
);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
createRoot(document.getElementById('root')!).render(
|
|
62
|
+
<StorefrontProvider data={readStorefrontData()}>
|
|
63
|
+
<CartProvider>
|
|
64
|
+
<BrowserRouter>
|
|
65
|
+
<Routes>
|
|
66
|
+
<Route path="/" element={<Shelf />} />
|
|
67
|
+
<Route path={`${ACCOUNT_PATH}/*`} element={<AccountPage frame={({ children }) => <>{children}</>} notFound={<p>Not found</p>} />} />
|
|
68
|
+
</Routes>
|
|
69
|
+
</BrowserRouter>
|
|
70
|
+
</CartProvider>
|
|
71
|
+
</StorefrontProvider>,
|
|
72
|
+
);
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`useCart()` also gives you line updates, coupons, the live quote and
|
|
76
|
+
`checkout()`, which sends the buyer to Shoppex checkout. Load the account with
|
|
77
|
+
`import()` in a real theme so it stays out of your main bundle.
|
|
78
|
+
|
|
79
|
+
## Features
|
|
80
|
+
|
|
81
|
+
- Catalog: product and bundle cards, categories, sorting, filtering, paging.
|
|
82
|
+
- Product pages: options, pricing per quantity, stock, badges, videos, the
|
|
83
|
+
rating breakdown.
|
|
84
|
+
- Cart: add, update, remove, coupons, quotes from the server, checkout
|
|
85
|
+
hand-off, per-product checkout fields.
|
|
86
|
+
- Reviews, shop pages, navigation menus and the contact form, from the SDK.
|
|
87
|
+
- Merchant rich text, sanitized before you render it.
|
|
88
|
+
- The customer account: sign-in, orders, downloads and keys, subscriptions,
|
|
89
|
+
rewards, referrals, reseller, support tickets and settings, in sixteen
|
|
90
|
+
languages.
|
|
91
|
+
- Money formatting: `$49`, `$49.50`, `¥1,200`.
|
|
92
|
+
|
|
93
|
+
## Theming the account
|
|
94
|
+
|
|
95
|
+
The account has no look of its own. `account.css` reads your theme's `--sx-*`
|
|
96
|
+
custom properties, so it takes your colours, type, radii and shadows in light
|
|
97
|
+
and dark mode. Define the tokens once:
|
|
98
|
+
|
|
99
|
+
```css
|
|
100
|
+
:root {
|
|
101
|
+
--sx-bg: #0a0b0e;
|
|
102
|
+
--sx-surface: #111318;
|
|
103
|
+
--sx-accent: #3b5bf0;
|
|
104
|
+
--sx-on-accent: #ffffff;
|
|
105
|
+
--sx-radius-card: 16px;
|
|
106
|
+
/* the full list is below */
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
To change one part, target its `sx-account-*` hook under `.sx-account`. Two
|
|
111
|
+
classes beat the account's one-class utilities:
|
|
112
|
+
|
|
113
|
+
```css
|
|
114
|
+
.sx-account .sx-account-card { border-radius: 0; box-shadow: none; }
|
|
115
|
+
.sx-account .sx-account-nav-link[aria-current='page'] { text-decoration: underline; }
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
The account's own classes carry an `sxa:` prefix, so they never collide with
|
|
119
|
+
yours, and nothing in the stylesheet selects your elements.
|
|
120
|
+
|
|
121
|
+
## Eject
|
|
122
|
+
|
|
123
|
+
When tokens and hooks are not enough and you want to own the account's markup,
|
|
124
|
+
copy it into your project:
|
|
125
|
+
|
|
126
|
+
1. Copy `node_modules/@shoppexio/storefront-react/eject/account/` to
|
|
127
|
+
`src/account/`. Its imports already point at `@shoppexio/storefront-react`.
|
|
128
|
+
2. Import `AccountPage` from `./account/account-page` instead of
|
|
129
|
+
`@shoppexio/storefront-react/account`.
|
|
130
|
+
3. Keep importing `@shoppexio/storefront-react/account.css`; it styles the
|
|
131
|
+
classes the copied markup carries.
|
|
132
|
+
|
|
133
|
+
From then on the account is yours, and package updates no longer change it.
|
|
134
|
+
Most themes never need this.
|
|
135
|
+
|
|
136
|
+
## Links
|
|
137
|
+
|
|
138
|
+
- Docs: [Code storefront development](https://docs.shoppex.io/storefront/code-storefront-development),
|
|
139
|
+
[Customer accounts](https://docs.shoppex.io/storefront/code-storefront-accounts)
|
|
140
|
+
- Example: the ForkMe template, a complete storefront built on this package.
|
|
141
|
+
Create a storefront from it in the Shoppex dashboard under
|
|
142
|
+
**Store → Storefronts**; see [Code storefronts](https://docs.shoppex.io/storefront/code-storefronts).
|
|
143
|
+
- [Changelog](./CHANGELOG.md)
|
|
144
|
+
- License: MIT
|
|
145
|
+
|
|
146
|
+
## Reference
|
|
147
|
+
|
|
148
|
+
### Entries
|
|
20
149
|
|
|
21
150
|
| Import | What it is |
|
|
22
151
|
|---|---|
|
|
@@ -24,7 +153,7 @@ Peer dependencies: `react` and `react-dom` 19.2, `react-router-dom` 7.18.
|
|
|
24
153
|
| `@shoppexio/storefront-react/account` | `AccountPage`, the whole customer account |
|
|
25
154
|
| `@shoppexio/storefront-react/account.css` | The account's stylesheet, plain CSS |
|
|
26
155
|
|
|
27
|
-
|
|
156
|
+
#### The root: where to start
|
|
28
157
|
|
|
29
158
|
| Module | Use it for | Start with |
|
|
30
159
|
|---|---|---|
|
|
@@ -42,42 +171,17 @@ Peer dependencies: `react` and `react-dom` 19.2, `react-router-dom` 7.18.
|
|
|
42
171
|
The `.d.ts` files next to the JS are the reference; every export carries its
|
|
43
172
|
contract in its doc comment.
|
|
44
173
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
```tsx
|
|
48
|
-
// src/pages/account-page.tsx, loaded with import() behind ACCOUNT_PATH
|
|
49
|
-
import '@shoppexio/storefront-react/account.css';
|
|
50
|
-
import { AccountPage as ShoppexAccount } from '@shoppexio/storefront-react/account';
|
|
51
|
-
import { PageShell } from '../components/layout/page-shell';
|
|
52
|
-
import { NotFoundPage } from './not-found-page';
|
|
53
|
-
|
|
54
|
-
function Frame({ children }: { children: React.ReactNode }) {
|
|
55
|
-
return <PageShell page="account">{children}</PageShell>;
|
|
56
|
-
}
|
|
57
|
-
|
|
58
|
-
export function AccountPage() {
|
|
59
|
-
return <ShoppexAccount frame={Frame} notFound={<NotFoundPage />} />;
|
|
60
|
-
}
|
|
61
|
-
```
|
|
174
|
+
### Account routing
|
|
62
175
|
|
|
63
|
-
- Mount
|
|
176
|
+
- Mount the account under `${ACCOUNT_PATH}/*` and `${ACCOUNT_PATH_ALIAS}/*`.
|
|
64
177
|
- Route every path in `ACCOUNT_STOREFRONT_ROUTES`; the account links to them.
|
|
65
178
|
- List every entry of `ACCOUNT_ARTIFACT_CAPABILITIES` in
|
|
66
179
|
`public/shoppex.capabilities.json`.
|
|
67
|
-
- The
|
|
68
|
-
sixteen storefront locales ship with the account.
|
|
180
|
+
- The account reads its language from `<html lang>`, which Shoppex sets.
|
|
69
181
|
|
|
70
|
-
|
|
182
|
+
### Account hooks
|
|
71
183
|
|
|
72
|
-
|
|
73
|
-
one of your theme's `--sx-*` custom properties, so it takes your palette, type,
|
|
74
|
-
radii and shadows, light and dark. Its utilities use the package-private `sxa:`
|
|
75
|
-
prefix, so they cannot collide with your classes, and nothing in it selects
|
|
76
|
-
your elements. It uses no cascade layer: a one-class `sxa:` rule beats your
|
|
77
|
-
element resets (`button { color: inherit }`), and a rule of yours scoped under
|
|
78
|
-
the root hook beats it.
|
|
79
|
-
|
|
80
|
-
To restyle a part, target its hook under `.sx-account`. Hooks carry no styles:
|
|
184
|
+
Hooks carry no styles:
|
|
81
185
|
|
|
82
186
|
`sx-account` (root), `sx-account-header`, `sx-account-title`,
|
|
83
187
|
`sx-account-signout`, `sx-account-nav`, `sx-account-nav-link`,
|
|
@@ -88,19 +192,14 @@ To restyle a part, target its hook under `.sx-account`. Hooks carry no styles:
|
|
|
88
192
|
`sx-account-status`, `sx-account-field`, `sx-account-label`,
|
|
89
193
|
`sx-account-field-error`.
|
|
90
194
|
|
|
91
|
-
```css
|
|
92
|
-
/* two classes beat the account's one-class utilities */
|
|
93
|
-
.sx-account .sx-account-card { border-radius: 0; box-shadow: none; }
|
|
94
|
-
.sx-account .sx-account-nav-link[aria-current='page'] { text-decoration: underline; }
|
|
95
|
-
```
|
|
96
|
-
|
|
97
195
|
`.sx-account` also scopes a zero-specificity baseline (box sizing, border
|
|
98
|
-
reset, heading font) for themes without a CSS reset.
|
|
196
|
+
reset, heading font) for themes without a CSS reset. The stylesheet uses no
|
|
197
|
+
cascade layer: a one-class `sxa:` rule beats your element resets, and a rule of
|
|
198
|
+
yours scoped under `.sx-account` beats it.
|
|
99
199
|
|
|
100
|
-
###
|
|
200
|
+
### CSS custom properties
|
|
101
201
|
|
|
102
|
-
A theme defines every one of these.
|
|
103
|
-
built stylesheet.
|
|
202
|
+
A theme defines every one of these.
|
|
104
203
|
|
|
105
204
|
<!-- css-contract:start -->
|
|
106
205
|
|
|
@@ -114,24 +213,3 @@ built stylesheet.
|
|
|
114
213
|
<!-- css-contract:end -->
|
|
115
214
|
|
|
116
215
|
Body text inherits the page's own font and colour.
|
|
117
|
-
|
|
118
|
-
## Ejecting the account
|
|
119
|
-
|
|
120
|
-
When restyling is not enough and you want to own the account's markup:
|
|
121
|
-
|
|
122
|
-
1. Copy `node_modules/@shoppexio/storefront-react/eject/account/` into your
|
|
123
|
-
project as `src/account/`. Its imports of the package root already point
|
|
124
|
-
at `@shoppexio/storefront-react`.
|
|
125
|
-
2. Import `AccountPage` from `./account/account-page` instead of
|
|
126
|
-
`@shoppexio/storefront-react/account`.
|
|
127
|
-
3. Keep importing `@shoppexio/storefront-react/account.css`: it styles the
|
|
128
|
-
`sxa:` classes the copied markup carries. New markup uses your own classes.
|
|
129
|
-
|
|
130
|
-
From then on the account is yours and a package update no longer reaches it.
|
|
131
|
-
A CLI command for this is planned.
|
|
132
|
-
|
|
133
|
-
## Versions
|
|
134
|
-
|
|
135
|
-
Official templates pin an exact version. Monorepo maintainers move every pin
|
|
136
|
-
at once with `bun run storefront-react:bump <version>` after publishing; see
|
|
137
|
-
`docs/runbooks/theme-runtime-release.md`.
|
package/package.json
CHANGED
|
@@ -1,14 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@shoppexio/storefront-react",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "React hooks, models and a customer account for Shoppex code storefronts",
|
|
5
5
|
"type": "module",
|
|
6
|
-
"repository": {
|
|
7
|
-
"type": "git",
|
|
8
|
-
"url": "git+https://github.com/ShoppexIO/shoppex.git",
|
|
9
|
-
"directory": "packages/storefront-react"
|
|
10
|
-
},
|
|
11
6
|
"homepage": "https://docs.shoppex.io/storefront/code-storefront-development",
|
|
7
|
+
"bugs": {
|
|
8
|
+
"email": "support@shoppex.io"
|
|
9
|
+
},
|
|
12
10
|
"publishConfig": {
|
|
13
11
|
"access": "public"
|
|
14
12
|
},
|
|
@@ -46,8 +44,14 @@
|
|
|
46
44
|
"keywords": [
|
|
47
45
|
"shoppex",
|
|
48
46
|
"storefront",
|
|
47
|
+
"code-storefront",
|
|
48
|
+
"headless",
|
|
49
|
+
"ecommerce",
|
|
49
50
|
"react",
|
|
50
|
-
"
|
|
51
|
+
"react-19",
|
|
52
|
+
"hooks",
|
|
53
|
+
"cart",
|
|
54
|
+
"customer-account"
|
|
51
55
|
],
|
|
52
56
|
"author": "Shoppex",
|
|
53
57
|
"license": "MIT",
|