create-znode-plugin 0.1.3 → 0.1.5

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 (3) hide show
  1. package/README.md +29 -7
  2. package/index.mjs +5 -3
  3. package/package.json +5 -2
package/README.md CHANGED
@@ -3,6 +3,17 @@
3
3
  Creates a Znode runtime theme project, the way `create-next-app` creates a Next.js app. The project builds on its own
4
4
  and runs inside your Znode store: no fork of the store, no webstore rebuild.
5
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).
9
+
10
+ ```bash
11
+ npm init znode-plugin@latest my-theme # 1. create (answer the store question)
12
+ cd my-theme
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)
15
+ ```
16
+
6
17
  ## Before you start
7
18
 
8
19
  | You need | Where to find it |
@@ -40,7 +51,8 @@ and you are asked for it.
40
51
  ```
41
52
  > npm create znode-plugin@latest my-theme
42
53
 
43
- Store path to connect (the store repo, with tsconfig.base.json), Enter to skip: D:\znode\my-store
54
+ Connect your Znode webstore (recommended: npm run dev needs it)
55
+ Webstore folder, the repo root that has tsconfig.base.json (e.g. D:\znode\webstore): D:\znode\my-store
44
56
  Store: D:\znode\my-store
45
57
  Plugin folder: D:\znode\runtime-plugins-store
46
58
  Created My Theme in D:\themes\my-theme
@@ -57,8 +69,8 @@ Then enable the theme for your stores in the plugin folder's plugins.json, and o
57
69
  | Step | What you see | What you do |
58
70
  | --- | --- | --- |
59
71
  | 1. Name | `Project name …` (only when you did not type one) | Type a name such as `my-theme` |
60
- | 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 |
61
- | 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 |
72
+ | 2. **Webstore folder** | `Connect your Znode webstore (recommended …)` then `Webstore folder, the repo root that has tsconfig.base.json (e.g. …):` | Type or paste the **store repo folder** (the one with `tsconfig.base.json`), then Enter |
73
+ | 3. **Plugin folder** | `Plugin folder: …` printed for you, or the question `Plugin folder the webstore loads themes from (its RUNTIME_PLUGINS_DIR, the folder with plugins.json):` | Nothing when it is printed. When asked: the folder the store's `RUNTIME_PLUGINS_DIR` points to |
62
74
  | 4. Files | `Created My Theme in …` | Nothing: the starter theme is copied and named |
63
75
  | 5. Install | `Installing dependencies…` | Nothing: `npm install` runs (`znode-plugin`, React and Next.js types) |
64
76
  | 6. Link | `linked … (69 store aliases)` | Nothing: the project now sees the store's real components and types |
@@ -70,10 +82,11 @@ Then enable the theme for your stores in the plugin folder's plugins.json, and o
70
82
  the plugin folder.
71
83
  - **Why:** the project gets the store's real types, so imports such as `@znode/base-components/...` are checked against
72
84
  the store's own code while you write your theme.
73
- - **A wrong folder** is not accepted: you see `… has no tsconfig.base.json` and the question again.
85
+ - **A wrong folder** is not accepted: you see `… has no tsconfig.base.json. Enter the webstore repo's root folder (or leave empty to skip).` and the question again.
74
86
  - **A default answer:** set `ZNODE_STORE_DIR` in your environment and it is shown in `[ ]`; press Enter to take it.
75
- - **Enter on an empty answer skips it.** The project is still created; connect it later with
76
- `npm run link-store -- <store repo>`.
87
+ - **Answer it (recommended).** An empty answer skips it (you then see `Skipped: npm run dev cannot deploy until you connect it …`): the project is still created, but `npm run dev` cannot
88
+ deploy and store imports are not type-checked until you connect it (`npm run link-store -- <store repo>` and a
89
+ `znode.local.json`).
77
90
 
78
91
  ### The plugin folder (step 3)
79
92
 
@@ -106,9 +119,17 @@ Then enable the theme for your stores in the plugin folder's plugins.json, and o
106
119
  http://localhost:3000/api/extensions/preview (back to the store's own theme)
107
120
  ```
108
121
 
109
- 4. To make it live for a store: in the plugin folder's `plugins.json`, set your theme's `"enabled": true` and add the
122
+ 4. Change a file under `src/`, save, wait for `installed theme my-theme@…` in the `npm run dev` window, and **reload the
123
+ page** (the store does not refresh an open page itself).
124
+
125
+ 5. To make it live for a store: in the plugin folder's `plugins.json`, set your theme's `"enabled": true` and add the
110
126
  store codes to `"stores"`.
111
127
 
128
+ **`npm run dev` or `npm run deploy`?** Both build and install. `dev` keeps watching and installs again on every save (use
129
+ it while you work); `deploy` installs once and exits (a fresh machine, after `git pull`, scripts and CI). You do not run
130
+ both. To release a new version, change `"version"` in `znode-package.json` first (see
131
+ [Versions](https://www.npmjs.com/package/znode-plugin#versions)).
132
+
112
133
  | Command | What it does |
113
134
  | --- | --- |
114
135
  | `npm run dev` | Build, deploy to the plugin folder, and again on every save |
@@ -165,4 +186,5 @@ npx create-znode-plugin@latest my-theme --store D:\znode\my-store --plugins-dir
165
186
  | `… exists and is not empty` | Choose another name, or empty that folder |
166
187
  | `needs the store's plugin folder` | Add `znode.local.json` with `{ "pluginsDir": "<the store's RUNTIME_PLUGINS_DIR>" }` |
167
188
  | Preview link returns 404 | The webstore is not in development mode, or the theme is not deployed yet (`npm run dev`) |
189
+ | `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 |
168
190
  | `@znode/...` imports are red in the editor | Run `npm run link-store -- <store repo>` |
package/index.mjs CHANGED
@@ -102,19 +102,21 @@ async function main() {
102
102
  if (options.store && !isStoreRepo(options.store)) fail(`--store ${options.store}: no tsconfig.base.json there (pass the store repo's folder)`);
103
103
  if (!options.store && interactive) {
104
104
  const suggested = process.env.ZNODE_STORE_DIR || "";
105
+ console.log("Connect your Znode webstore (recommended: npm run dev needs it)");
105
106
  for (;;) {
106
- const answer = (await ask(`Store path to connect (the store repo, with tsconfig.base.json)${suggested ? ` [${suggested}]` : ""}, Enter to skip: `)) || suggested;
107
+ const answer = (await ask(`Webstore folder, the repo root that has tsconfig.base.json${suggested ? ` [${suggested}]` : " (e.g. D:\\znode\\webstore)"}: `)) || suggested;
107
108
  if (!answer) break;
108
109
  if (isStoreRepo(answer)) {
109
110
  options.store = answer;
110
111
  break;
111
112
  }
112
- console.log(` ${path.resolve(answer)} has no tsconfig.base.json: enter the store repo's folder, or press Enter to skip`);
113
+ console.log(` ${path.resolve(answer)} has no tsconfig.base.json. Enter the webstore repo's root folder (or leave empty to skip).`);
113
114
  }
115
+ if (!options.store) console.log(" Skipped: npm run dev cannot deploy until you connect it (npm run link-store -- <webstore repo>).");
114
116
  }
115
117
  if (options.store && !options.pluginsDir) options.pluginsDir = storePluginsDir(options.store);
116
118
  if (options.store && !options.pluginsDir && interactive) {
117
- options.pluginsDir = (await ask("The store's plugin folder (its RUNTIME_PLUGINS_DIR), Enter to skip: ")) || undefined;
119
+ options.pluginsDir = (await ask("Plugin folder the webstore loads themes from (its RUNTIME_PLUGINS_DIR, the folder with plugins.json): ")) || undefined;
118
120
  }
119
121
  prompt?.close();
120
122
  if (options.store) console.log(`Store: ${path.resolve(options.store)}${options.pluginsDir ? `\nPlugin folder: ${path.resolve(options.pluginsDir)}` : ""}`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-znode-plugin",
3
- "version": "0.1.3",
3
+ "version": "0.1.5",
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": { "registry": "https://registry.npmjs.org/", "access": "public" }
24
+ "publishConfig": {
25
+ "registry": "https://registry.npmjs.org/",
26
+ "access": "public"
27
+ }
25
28
  }