create-znode-plugin 0.1.2 → 0.1.4
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/README.md +172 -19
- package/package.json +5 -2
package/README.md
CHANGED
|
@@ -1,36 +1,189 @@
|
|
|
1
1
|
# create-znode-plugin
|
|
2
2
|
|
|
3
|
-
Creates a Znode runtime theme project, the way `create-next-app` creates a Next.js app.
|
|
3
|
+
Creates a Znode runtime theme project, the way `create-next-app` creates a Next.js app. The project builds on its own
|
|
4
|
+
and runs inside your Znode store: no fork of the store, no webstore rebuild.
|
|
5
|
+
|
|
6
|
+
**In short:** you write a theme in its own folder (its own git repo); `npm run dev` builds it and copies it into the store's
|
|
7
|
+
plugin folder; the running webstore loads it, and you see it with a preview link in your browser only. Examples (colors,
|
|
8
|
+
slots, widgets, settings, pages), versions and every command: [`znode-plugin`](https://www.npmjs.com/package/znode-plugin).
|
|
4
9
|
|
|
5
10
|
```bash
|
|
6
|
-
npm
|
|
11
|
+
npm init znode-plugin@latest my-theme # 1. create (answer the store question)
|
|
7
12
|
cd my-theme
|
|
8
|
-
npm run dev
|
|
13
|
+
npm run dev # 2. build + deploy, again on every save
|
|
14
|
+
# 3. open http://localhost:3000/api/extensions/preview?theme=my-theme (webstore running: npx nx dev webstore)
|
|
9
15
|
```
|
|
10
16
|
|
|
11
|
-
|
|
17
|
+
## Before you start
|
|
18
|
+
|
|
19
|
+
| You need | Where to find it |
|
|
20
|
+
| --- | --- |
|
|
21
|
+
| Node.js 20 or newer | `node -v` |
|
|
22
|
+
| **The store repo**, checked out on this machine | The folder that has `tsconfig.base.json` at its root (the webstore and page builder repo), e.g. `D:\znode\my-store` |
|
|
23
|
+
| **The store's plugin folder** | The folder the webstore loads runtime packages from: the `RUNTIME_PLUGINS_DIR` line in the store's `apps/webstore/.env.local` (or `.env`), e.g. `D:\znode\runtime-plugins-store` |
|
|
24
|
+
|
|
25
|
+
You will be asked for the store repo. The plugin folder is usually found for you (step 3 below).
|
|
26
|
+
|
|
27
|
+
## 1. Run one of these
|
|
28
|
+
|
|
29
|
+
All three run this package; use the one you like.
|
|
12
30
|
|
|
31
|
+
```bash
|
|
32
|
+
npm create znode-plugin@latest my-theme
|
|
13
33
|
```
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
npx create-znode-plugin@latest my-theme
|
|
17
37
|
```
|
|
18
38
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
-
|
|
24
|
-
|
|
39
|
+
```bash
|
|
40
|
+
npm init znode-plugin@latest my-theme
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
`my-theme` is your project's name and folder: lowercase letters, digits and dashes (2 to 49 characters). Leave it out
|
|
44
|
+
and you are asked for it.
|
|
45
|
+
|
|
46
|
+
> `npx create znode-plugin` (with a space) does **not** work: npx would look for a package called `create`. With `npx`,
|
|
47
|
+
> type the full name `create-znode-plugin`.
|
|
48
|
+
|
|
49
|
+
## 2. What happens next, step by step
|
|
50
|
+
|
|
51
|
+
```
|
|
52
|
+
> npm create znode-plugin@latest my-theme
|
|
53
|
+
|
|
54
|
+
Store path to connect (the store repo, with tsconfig.base.json), Enter to skip: D:\znode\my-store
|
|
55
|
+
Store: D:\znode\my-store
|
|
56
|
+
Plugin folder: D:\znode\runtime-plugins-store
|
|
57
|
+
Created My Theme in D:\themes\my-theme
|
|
58
|
+
Installing dependencies…
|
|
59
|
+
added 32 packages in 30s
|
|
60
|
+
linked D:\themes\my-theme\tsconfig.store.json to D:\znode\my-store\tsconfig.base.json (69 store aliases)
|
|
61
|
+
|
|
62
|
+
Next:
|
|
63
|
+
cd my-theme
|
|
64
|
+
npm run dev (build, deploy, and again on every save)
|
|
65
|
+
Then enable the theme for your stores in the plugin folder's plugins.json, and open /my-theme-welcome.
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
| Step | What you see | What you do |
|
|
69
|
+
| --- | --- | --- |
|
|
70
|
+
| 1. Name | `Project name …` (only when you did not type one) | Type a name such as `my-theme` |
|
|
71
|
+
| 2. **Store path** | `Store path to connect (the store repo, with tsconfig.base.json), Enter to skip:` | Type or paste the **store repo folder** (the one with `tsconfig.base.json`), then Enter |
|
|
72
|
+
| 3. **Plugin folder** | `Plugin folder: …` printed for you, or the question `The store's plugin folder (its RUNTIME_PLUGINS_DIR), Enter to skip:` | Nothing when it is printed. When asked: the folder the store's `RUNTIME_PLUGINS_DIR` points to |
|
|
73
|
+
| 4. Files | `Created My Theme in …` | Nothing: the starter theme is copied and named |
|
|
74
|
+
| 5. Install | `Installing dependencies…` | Nothing: `npm install` runs (`znode-plugin`, React and Next.js types) |
|
|
75
|
+
| 6. Link | `linked … (69 store aliases)` | Nothing: the project now sees the store's real components and types |
|
|
76
|
+
| 7. Next | `Next:` | Run the commands it prints (section 3) |
|
|
77
|
+
|
|
78
|
+
### The store path question (step 2)
|
|
79
|
+
|
|
80
|
+
- **What to enter:** the root of the store repo, the folder with `tsconfig.base.json` in it. Not `apps/webstore`, not
|
|
81
|
+
the plugin folder.
|
|
82
|
+
- **Why:** the project gets the store's real types, so imports such as `@znode/base-components/...` are checked against
|
|
83
|
+
the store's own code while you write your theme.
|
|
84
|
+
- **A wrong folder** is not accepted: you see `… has no tsconfig.base.json` and the question again.
|
|
85
|
+
- **A default answer:** set `ZNODE_STORE_DIR` in your environment and it is shown in `[ ]`; press Enter to take it.
|
|
86
|
+
- **Answer it (recommended).** Enter on an empty answer skips it: the project is still created, but `npm run dev` cannot
|
|
87
|
+
deploy and store imports are not type-checked until you connect it (`npm run link-store -- <store repo>` and a
|
|
88
|
+
`znode.local.json`).
|
|
89
|
+
|
|
90
|
+
### The plugin folder (step 3)
|
|
91
|
+
|
|
92
|
+
- **Found for you** when the store sets `RUNTIME_PLUGINS_DIR` in `apps/webstore/.env.local` (or `.env`). Only that one
|
|
93
|
+
line is read from the file, nothing else.
|
|
94
|
+
- **Asked** when the store does not set it: enter the folder the webstore loads runtime packages from (it holds
|
|
95
|
+
`plugins.json`).
|
|
96
|
+
- **Why:** `npm run dev` and `npm run deploy` copy your built theme there.
|
|
97
|
+
- It is saved in the project's `znode.local.json` (`{ "pluginsDir": "…" }`), which is git-ignored: each developer keeps
|
|
98
|
+
their own.
|
|
99
|
+
- **Skipped:** create `znode.local.json` yourself later, or pass the folder to the command
|
|
100
|
+
(`npm run deploy -- <plugin folder>`).
|
|
101
|
+
|
|
102
|
+
## 3. After it is created
|
|
103
|
+
|
|
104
|
+
1. Build and deploy, again on every save:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
cd my-theme
|
|
108
|
+
npm run dev
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
2. Start the store's webstore in development mode (in the store repo).
|
|
112
|
+
|
|
113
|
+
3. Look at your theme in your browser only, without changing anything for shoppers (development mode only):
|
|
114
|
+
|
|
115
|
+
```
|
|
116
|
+
http://localhost:3000/api/extensions/preview?theme=my-theme
|
|
117
|
+
http://localhost:3000/api/extensions/preview?theme=my-theme&to=/my-theme-welcome
|
|
118
|
+
http://localhost:3000/api/extensions/preview (back to the store's own theme)
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
4. Change a file under `src/`, save, wait for `installed theme my-theme@…` in the `npm run dev` window, and **reload the
|
|
122
|
+
page** (the store does not refresh an open page itself).
|
|
123
|
+
|
|
124
|
+
5. To make it live for a store: in the plugin folder's `plugins.json`, set your theme's `"enabled": true` and add the
|
|
125
|
+
store codes to `"stores"`.
|
|
126
|
+
|
|
127
|
+
**`npm run dev` or `npm run deploy`?** Both build and install. `dev` keeps watching and installs again on every save (use
|
|
128
|
+
it while you work); `deploy` installs once and exits (a fresh machine, after `git pull`, scripts and CI). You do not run
|
|
129
|
+
both. To release a new version, change `"version"` in `znode-package.json` first (see
|
|
130
|
+
[Versions](https://www.npmjs.com/package/znode-plugin#versions)).
|
|
131
|
+
|
|
132
|
+
| Command | What it does |
|
|
133
|
+
| --- | --- |
|
|
134
|
+
| `npm run dev` | Build, deploy to the plugin folder, and again on every save |
|
|
135
|
+
| `npm run build` | Type-check and build into `dist/` |
|
|
136
|
+
| `npm run check` | Marketplace checks (metadata, permissions, settings, sizes) |
|
|
137
|
+
| `npm run pack` | Build and zip into `releases/` |
|
|
138
|
+
| `npm run deploy` | Pack and install into the plugin folder once |
|
|
139
|
+
| `npm run link-store -- <store repo>` | Connect (or reconnect) the store's types |
|
|
140
|
+
|
|
141
|
+
## What is in the project
|
|
142
|
+
|
|
143
|
+
```
|
|
144
|
+
my-theme/
|
|
145
|
+
znode-package.json name, version, kind "theme", settings, server pages
|
|
146
|
+
src/browser.tsx slots (wrap or replace parts of the store) and page-builder widgets
|
|
147
|
+
src/server.tsx layouts around pages, whole pages at new URLs, API routes
|
|
148
|
+
src/slots/ AnnouncementBar (layout.header), ProductBadge (product.card)
|
|
149
|
+
src/widgets/ a Hero widget for the page builder
|
|
150
|
+
src/server/ ThemeLayout (layout.root), WelcomePage (/my-theme-welcome)
|
|
151
|
+
src/styles/theme.css the theme's styles
|
|
152
|
+
src/i18n/labels.json the theme's labels
|
|
153
|
+
tsconfig.store.json this machine's link to the store's types (git-ignored)
|
|
154
|
+
znode.local.json this machine's plugin folder (git-ignored)
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Where each kind of customization goes (styles, layouts, slots, widgets, pages, routes, settings, labels): see
|
|
158
|
+
[`znode-plugin`](https://www.npmjs.com/package/znode-plugin).
|
|
159
|
+
|
|
160
|
+
## Without questions (scripts and CI)
|
|
161
|
+
|
|
162
|
+
When there is no terminal to answer, nothing is asked: pass the answers as options. With `npm create` and `npm init`
|
|
163
|
+
the options go after `--`; with `npx` they follow the name directly.
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
npm create znode-plugin@latest my-theme -- --store D:\znode\my-store
|
|
167
|
+
npx create-znode-plugin@latest my-theme --store D:\znode\my-store --plugins-dir D:\znode\runtime-plugins-store
|
|
168
|
+
```
|
|
25
169
|
|
|
26
170
|
| Option | Meaning |
|
|
27
171
|
| --- | --- |
|
|
28
|
-
| `--store <dir>` | The store repo (with `tsconfig.base.json`)
|
|
29
|
-
| `--plugins-dir <dir>` | The store's plugin folder, when the store does not set `RUNTIME_PLUGINS_DIR
|
|
172
|
+
| `--store <dir>` | The store repo (with `tsconfig.base.json`); skips the store question |
|
|
173
|
+
| `--plugins-dir <dir>` | The store's plugin folder, when the store does not set `RUNTIME_PLUGINS_DIR` |
|
|
30
174
|
| `--publisher <name>` | Publisher shown in the marketplace |
|
|
31
175
|
| `--registry <url>` | npm registry for the project's dependencies (written to its `.npmrc`) |
|
|
32
|
-
| `--no-install` | Skip `npm install` |
|
|
176
|
+
| `--no-install` | Skip `npm install` (and the store link, which needs it) |
|
|
177
|
+
|
|
178
|
+
## Troubleshooting
|
|
33
179
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
180
|
+
| You see | Do this |
|
|
181
|
+
| --- | --- |
|
|
182
|
+
| `npm error 404 … create` | You typed `npx create znode-plugin`: use `npx create-znode-plugin@latest` or `npm create znode-plugin@latest` |
|
|
183
|
+
| No store question | Not a terminal (scripts, CI, some IDE consoles): pass `--store`. Or an old cached version: keep `@latest` |
|
|
184
|
+
| `… has no tsconfig.base.json` | You gave a subfolder (`apps/webstore`) or the plugin folder: give the store repo's root |
|
|
185
|
+
| `… exists and is not empty` | Choose another name, or empty that folder |
|
|
186
|
+
| `needs the store's plugin folder` | Add `znode.local.json` with `{ "pluginsDir": "<the store's RUNTIME_PLUGINS_DIR>" }` |
|
|
187
|
+
| Preview link returns 404 | The webstore is not in development mode, or the theme is not deployed yet (`npm run dev`) |
|
|
188
|
+
| `installed …` but no change in the store | The theme went to another plugin folder than the running webstore reads: compare `znode.local.json` with the webstore's `RUNTIME_PLUGINS_DIR` (`apps/webstore/.env.local` or `.env`), then reload |
|
|
189
|
+
| `@znode/...` imports are red in the editor | Run `npm run link-store -- <store repo>` |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "create-znode-plugin",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.4",
|
|
4
4
|
"description": "Create a Znode runtime theme project: npm create znode-plugin@latest <name>.",
|
|
5
5
|
"license": "UNLICENSED",
|
|
6
6
|
"type": "module",
|
|
@@ -21,5 +21,8 @@
|
|
|
21
21
|
"theme",
|
|
22
22
|
"create"
|
|
23
23
|
],
|
|
24
|
-
"publishConfig": {
|
|
24
|
+
"publishConfig": {
|
|
25
|
+
"registry": "https://registry.npmjs.org/",
|
|
26
|
+
"access": "public"
|
|
27
|
+
}
|
|
25
28
|
}
|