create-znode-plugin 0.0.0-stage → 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/README.md CHANGED
@@ -1,3 +1,168 @@
1
- # Temporary Holding Version
1
+ # create-znode-plugin
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
+ ## Before you start
7
+
8
+ | You need | Where to find it |
9
+ | --- | --- |
10
+ | Node.js 20 or newer | `node -v` |
11
+ | **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` |
12
+ | **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` |
13
+
14
+ You will be asked for the store repo. The plugin folder is usually found for you (step 3 below).
15
+
16
+ ## 1. Run one of these
17
+
18
+ All three run this package; use the one you like.
19
+
20
+ ```bash
21
+ npm create znode-plugin@latest my-theme
22
+ ```
23
+
24
+ ```bash
25
+ npx create-znode-plugin@latest my-theme
26
+ ```
27
+
28
+ ```bash
29
+ npm init znode-plugin@latest my-theme
30
+ ```
31
+
32
+ `my-theme` is your project's name and folder: lowercase letters, digits and dashes (2 to 49 characters). Leave it out
33
+ and you are asked for it.
34
+
35
+ > `npx create znode-plugin` (with a space) does **not** work: npx would look for a package called `create`. With `npx`,
36
+ > type the full name `create-znode-plugin`.
37
+
38
+ ## 2. What happens next, step by step
39
+
40
+ ```
41
+ > npm create znode-plugin@latest my-theme
42
+
43
+ Store path to connect (the store repo, with tsconfig.base.json), Enter to skip: D:\znode\my-store
44
+ Store: D:\znode\my-store
45
+ Plugin folder: D:\znode\runtime-plugins-store
46
+ Created My Theme in D:\themes\my-theme
47
+ Installing dependencies…
48
+ added 32 packages in 30s
49
+ linked D:\themes\my-theme\tsconfig.store.json to D:\znode\my-store\tsconfig.base.json (69 store aliases)
50
+
51
+ Next:
52
+ cd my-theme
53
+ npm run dev (build, deploy, and again on every save)
54
+ Then enable the theme for your stores in the plugin folder's plugins.json, and open /my-theme-welcome.
55
+ ```
56
+
57
+ | Step | What you see | What you do |
58
+ | --- | --- | --- |
59
+ | 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 |
62
+ | 4. Files | `Created My Theme in …` | Nothing: the starter theme is copied and named |
63
+ | 5. Install | `Installing dependencies…` | Nothing: `npm install` runs (`znode-plugin`, React and Next.js types) |
64
+ | 6. Link | `linked … (69 store aliases)` | Nothing: the project now sees the store's real components and types |
65
+ | 7. Next | `Next:` | Run the commands it prints (section 3) |
66
+
67
+ ### The store path question (step 2)
68
+
69
+ - **What to enter:** the root of the store repo, the folder with `tsconfig.base.json` in it. Not `apps/webstore`, not
70
+ the plugin folder.
71
+ - **Why:** the project gets the store's real types, so imports such as `@znode/base-components/...` are checked against
72
+ 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.
74
+ - **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>`.
77
+
78
+ ### The plugin folder (step 3)
79
+
80
+ - **Found for you** when the store sets `RUNTIME_PLUGINS_DIR` in `apps/webstore/.env.local` (or `.env`). Only that one
81
+ line is read from the file, nothing else.
82
+ - **Asked** when the store does not set it: enter the folder the webstore loads runtime packages from (it holds
83
+ `plugins.json`).
84
+ - **Why:** `npm run dev` and `npm run deploy` copy your built theme there.
85
+ - It is saved in the project's `znode.local.json` (`{ "pluginsDir": "…" }`), which is git-ignored: each developer keeps
86
+ their own.
87
+ - **Skipped:** create `znode.local.json` yourself later, or pass the folder to the command
88
+ (`npm run deploy -- <plugin folder>`).
89
+
90
+ ## 3. After it is created
91
+
92
+ 1. Build and deploy, again on every save:
93
+
94
+ ```bash
95
+ cd my-theme
96
+ npm run dev
97
+ ```
98
+
99
+ 2. Start the store's webstore in development mode (in the store repo).
100
+
101
+ 3. Look at your theme in your browser only, without changing anything for shoppers (development mode only):
102
+
103
+ ```
104
+ http://localhost:3000/api/extensions/preview?theme=my-theme
105
+ http://localhost:3000/api/extensions/preview?theme=my-theme&to=/my-theme-welcome
106
+ http://localhost:3000/api/extensions/preview (back to the store's own theme)
107
+ ```
108
+
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
110
+ store codes to `"stores"`.
111
+
112
+ | Command | What it does |
113
+ | --- | --- |
114
+ | `npm run dev` | Build, deploy to the plugin folder, and again on every save |
115
+ | `npm run build` | Type-check and build into `dist/` |
116
+ | `npm run check` | Marketplace checks (metadata, permissions, settings, sizes) |
117
+ | `npm run pack` | Build and zip into `releases/` |
118
+ | `npm run deploy` | Pack and install into the plugin folder once |
119
+ | `npm run link-store -- <store repo>` | Connect (or reconnect) the store's types |
120
+
121
+ ## What is in the project
122
+
123
+ ```
124
+ my-theme/
125
+ znode-package.json name, version, kind "theme", settings, server pages
126
+ src/browser.tsx slots (wrap or replace parts of the store) and page-builder widgets
127
+ src/server.tsx layouts around pages, whole pages at new URLs, API routes
128
+ src/slots/ AnnouncementBar (layout.header), ProductBadge (product.card)
129
+ src/widgets/ a Hero widget for the page builder
130
+ src/server/ ThemeLayout (layout.root), WelcomePage (/my-theme-welcome)
131
+ src/styles/theme.css the theme's styles
132
+ src/i18n/labels.json the theme's labels
133
+ tsconfig.store.json this machine's link to the store's types (git-ignored)
134
+ znode.local.json this machine's plugin folder (git-ignored)
135
+ ```
136
+
137
+ Where each kind of customization goes (styles, layouts, slots, widgets, pages, routes, settings, labels): see
138
+ [`znode-plugin`](https://www.npmjs.com/package/znode-plugin).
139
+
140
+ ## Without questions (scripts and CI)
141
+
142
+ When there is no terminal to answer, nothing is asked: pass the answers as options. With `npm create` and `npm init`
143
+ the options go after `--`; with `npx` they follow the name directly.
144
+
145
+ ```bash
146
+ npm create znode-plugin@latest my-theme -- --store D:\znode\my-store
147
+ npx create-znode-plugin@latest my-theme --store D:\znode\my-store --plugins-dir D:\znode\runtime-plugins-store
148
+ ```
149
+
150
+ | Option | Meaning |
151
+ | --- | --- |
152
+ | `--store <dir>` | The store repo (with `tsconfig.base.json`); skips the store question |
153
+ | `--plugins-dir <dir>` | The store's plugin folder, when the store does not set `RUNTIME_PLUGINS_DIR` |
154
+ | `--publisher <name>` | Publisher shown in the marketplace |
155
+ | `--registry <url>` | npm registry for the project's dependencies (written to its `.npmrc`) |
156
+ | `--no-install` | Skip `npm install` (and the store link, which needs it) |
157
+
158
+ ## Troubleshooting
159
+
160
+ | You see | Do this |
161
+ | --- | --- |
162
+ | `npm error 404 … create` | You typed `npx create znode-plugin`: use `npx create-znode-plugin@latest` or `npm create znode-plugin@latest` |
163
+ | No store question | Not a terminal (scripts, CI, some IDE consoles): pass `--store`. Or an old cached version: keep `@latest` |
164
+ | `… has no tsconfig.base.json` | You gave a subfolder (`apps/webstore`) or the plugin folder: give the store repo's root |
165
+ | `… exists and is not empty` | Choose another name, or empty that folder |
166
+ | `needs the store's plugin folder` | Add `znode.local.json` with `{ "pluginsDir": "<the store's RUNTIME_PLUGINS_DIR>" }` |
167
+ | Preview link returns 404 | The webstore is not in development mode, or the theme is not deployed yet (`npm run dev`) |
168
+ | `@znode/...` imports are red in the editor | Run `npm run link-store -- <store repo>` |
package/index.mjs ADDED
@@ -0,0 +1,145 @@
1
+ #!/usr/bin/env node
2
+ // create-znode-plugin: a new Znode runtime theme project, the way create-next-app makes a Next.js app.
3
+ //
4
+ // npm create znode-plugin@latest <name> (asks for the store to connect)
5
+ // npm create znode-plugin@latest <name> -- [--store <store repo>] [--plugins-dir <store plugin folder>]
6
+ // [--publisher <name>] [--registry <url>] [--no-install]
7
+ //
8
+ // It copies the template (template/theme), fills in the names, installs the dependencies (znode-plugin, react, next
9
+ // for their types), and, when given, links the store's types (--store) and the store's plugin folder (--plugins-dir).
10
+
11
+ import fs from "node:fs";
12
+ import path from "node:path";
13
+ import readline from "node:readline/promises";
14
+ import { spawnSync } from "node:child_process";
15
+ import { fileURLToPath } from "node:url";
16
+
17
+ const HERE = path.dirname(fileURLToPath(import.meta.url));
18
+ const NAME = /^[a-z0-9][a-z0-9-]{1,48}$/;
19
+ // npm drops .gitignore files from a published package: the template keeps it as "gitignore"
20
+ const RENAMES = { gitignore: ".gitignore" };
21
+ const TEXT = new Set([".json", ".ts", ".tsx", ".css", ".md", ".svg", ""]);
22
+
23
+ const fail = (message) => {
24
+ console.error(`create-znode-plugin: ${message}`);
25
+ process.exit(1);
26
+ };
27
+
28
+ function parseArgs(argv) {
29
+ const options = { install: true };
30
+ const rest = [];
31
+ for (let index = 0; index < argv.length; index++) {
32
+ const arg = argv[index];
33
+ const value = () => argv[++index] ?? fail(`${arg} needs a value`);
34
+ if (arg === "--plugins-dir") options.pluginsDir = value();
35
+ else if (arg === "--store") options.store = value();
36
+ else if (arg === "--publisher") options.publisher = value();
37
+ else if (arg === "--registry") options.registry = value();
38
+ else if (arg === "--kind") options.kind = value();
39
+ else if (arg === "--no-install") options.install = false;
40
+ else if (arg.startsWith("--")) fail(`unknown option ${arg}`);
41
+ else rest.push(arg);
42
+ }
43
+ options.name = rest[0];
44
+ return options;
45
+ }
46
+
47
+ const pascal = (name) => name.replace(/(^|-)([a-z0-9])/g, (_, __, letter) => letter.toUpperCase());
48
+ const label = (name) => name.replace(/(^|-)([a-z0-9])/g, (_, dash, letter) => (dash ? " " : "") + letter.toUpperCase());
49
+
50
+ // every template file into target, the placeholders in its name and text filled in
51
+ function copyTemplate(from, to, values) {
52
+ const fill = (text) => text.replace(/__(NAME|PASCAL|LABEL|PUBLISHER)__/g, (_, key) => values[key]);
53
+ for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
54
+ const source = path.join(from, entry.name);
55
+ const target = path.join(to, fill(RENAMES[entry.name] || entry.name));
56
+ if (entry.isDirectory()) {
57
+ fs.mkdirSync(target, { recursive: true });
58
+ copyTemplate(source, target, values);
59
+ } else if (TEXT.has(path.extname(entry.name))) {
60
+ fs.writeFileSync(target, fill(fs.readFileSync(source, "utf8")));
61
+ } else {
62
+ fs.copyFileSync(source, target);
63
+ }
64
+ }
65
+ }
66
+
67
+ const run = (command, args, cwd) => spawnSync(command, args, { cwd, stdio: "inherit", shell: process.platform === "win32" }).status === 0;
68
+
69
+ const isStoreRepo = (dir) => fs.existsSync(path.join(path.resolve(dir), "tsconfig.base.json"));
70
+
71
+ // the store's plugin folder, as the store itself is set up: RUNTIME_PLUGINS_DIR in the webstore's .env.local (else
72
+ // .env). Only that one line is read.
73
+ function storePluginsDir(storeRepo) {
74
+ for (const file of ["apps/webstore/.env.local", "apps/webstore/.env"]) {
75
+ try {
76
+ const line = fs.readFileSync(path.join(path.resolve(storeRepo), file), "utf8").match(/^\s*RUNTIME_PLUGINS_DIR\s*=\s*"?([^"\r\n]+?)"?\s*$/m);
77
+ if (line) return path.resolve(path.resolve(storeRepo), "apps/webstore", line[1]);
78
+ } catch {
79
+ // not there: the next file
80
+ }
81
+ }
82
+ return null;
83
+ }
84
+
85
+ async function main() {
86
+ const options = parseArgs(process.argv.slice(2));
87
+ if (options.kind && options.kind !== "theme") fail(`--kind ${options.kind}: only "theme" projects for now`);
88
+ // questions only when someone can answer them (a terminal); in scripts and CI the flags decide
89
+ const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
90
+ let prompt = null;
91
+ const ask = async (question) => {
92
+ prompt ||= readline.createInterface({ input: process.stdin, output: process.stdout });
93
+ return (await prompt.question(question)).trim();
94
+ };
95
+
96
+ if (!options.name && interactive) options.name = await ask("Project name (lowercase letters, digits, dashes): ");
97
+ if (!NAME.test(options.name || "")) fail("the name must be lowercase letters, digits and dashes (2 to 49)");
98
+ const target = path.resolve(options.name);
99
+ if (fs.existsSync(target) && fs.readdirSync(target).length) fail(`${target} exists and is not empty`);
100
+
101
+ // connect to the store: its repo gives the store's types (link-store) and, from its own settings, its plugin folder
102
+ if (options.store && !isStoreRepo(options.store)) fail(`--store ${options.store}: no tsconfig.base.json there (pass the store repo's folder)`);
103
+ if (!options.store && interactive) {
104
+ const suggested = process.env.ZNODE_STORE_DIR || "";
105
+ for (;;) {
106
+ const answer = (await ask(`Store path to connect (the store repo, with tsconfig.base.json)${suggested ? ` [${suggested}]` : ""}, Enter to skip: `)) || suggested;
107
+ if (!answer) break;
108
+ if (isStoreRepo(answer)) {
109
+ options.store = answer;
110
+ break;
111
+ }
112
+ console.log(` ${path.resolve(answer)} has no tsconfig.base.json: enter the store repo's folder, or press Enter to skip`);
113
+ }
114
+ }
115
+ if (options.store && !options.pluginsDir) options.pluginsDir = storePluginsDir(options.store);
116
+ if (options.store && !options.pluginsDir && interactive) {
117
+ options.pluginsDir = (await ask("The store's plugin folder (its RUNTIME_PLUGINS_DIR), Enter to skip: ")) || undefined;
118
+ }
119
+ prompt?.close();
120
+ if (options.store) console.log(`Store: ${path.resolve(options.store)}${options.pluginsDir ? `\nPlugin folder: ${path.resolve(options.pluginsDir)}` : ""}`);
121
+
122
+ const values = { NAME: options.name, PASCAL: pascal(options.name), LABEL: label(options.name), PUBLISHER: options.publisher || `${label(options.name)} team` };
123
+ fs.mkdirSync(target, { recursive: true });
124
+ copyTemplate(path.join(HERE, "template", "theme"), target, values);
125
+ // this machine's links, both git-ignored: no store types yet (npm run link-store), and the store's plugin folder
126
+ fs.writeFileSync(path.join(target, "tsconfig.store.json"), JSON.stringify({ extends: "znode-plugin/tsconfig.json" }, null, 2) + "\n");
127
+ if (options.pluginsDir) fs.writeFileSync(path.join(target, "znode.local.json"), JSON.stringify({ pluginsDir: path.resolve(options.pluginsDir) }, null, 2) + "\n");
128
+ if (options.registry) fs.writeFileSync(path.join(target, ".npmrc"), `registry=${options.registry}\n`);
129
+ console.log(`Created ${values.LABEL} in ${target}`);
130
+
131
+ if (options.install) {
132
+ console.log("Installing dependencies…");
133
+ if (!run("npm", ["install", "--no-audit", "--no-fund"], target)) fail("npm install failed: run it yourself in the project folder");
134
+ if (options.store && !run("npx", ["znode", "link-store", path.resolve(options.store), "."], target)) fail("linking the store failed: npm run link-store -- <store repo>");
135
+ }
136
+
137
+ const cd = path.relative(process.cwd(), target) || ".";
138
+ console.log(`
139
+ Next:
140
+ cd ${cd}${options.install ? "" : "\n npm install"}${options.store ? "" : "\n npm run link-store -- <store repo> (the store's real types)"}${options.pluginsDir ? "" : '\n add znode.local.json: { "pluginsDir": "<the store\'s RUNTIME_PLUGINS_DIR>" }'}
141
+ npm run dev (build, deploy, and again on every save)
142
+ Then enable the theme for your stores in the plugin folder's plugins.json, and open /${options.name}-welcome.`);
143
+ }
144
+
145
+ main();
package/package.json CHANGED
@@ -1,6 +1,25 @@
1
1
  {
2
2
  "name": "create-znode-plugin",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.3",
4
+ "description": "Create a Znode runtime theme project: npm create znode-plugin@latest <name>.",
5
+ "license": "UNLICENSED",
6
+ "type": "module",
7
+ "bin": {
8
+ "create-znode-plugin": "index.mjs"
9
+ },
10
+ "files": [
11
+ "index.mjs",
12
+ "template",
13
+ "README.md"
14
+ ],
15
+ "engines": {
16
+ "node": ">=20"
17
+ },
18
+ "keywords": [
19
+ "znode",
20
+ "runtime-plugin",
21
+ "theme",
22
+ "create"
23
+ ],
24
+ "publishConfig": { "registry": "https://registry.npmjs.org/", "access": "public" }
25
+ }
@@ -0,0 +1,36 @@
1
+ # __LABEL__
2
+
3
+ A Znode runtime theme, made with `create-znode-plugin`. It is built and deployed on its own and runs in the webstore
4
+ for the stores it is enabled for: no fork of the store, no webstore rebuild.
5
+
6
+ ## Commands
7
+
8
+ | Command | What it does |
9
+ | --- | --- |
10
+ | `npm run dev` | Build and deploy now, then again on every save; refresh the store page to see it |
11
+ | `npm run build` | Type-check against the store, then build into `dist/` |
12
+ | `npm run check` | The marketplace review: metadata, permissions against the code, sizes |
13
+ | `npm run pack` | Build and zip into `releases/__NAME__-<version>.zpkg.zip` |
14
+ | `npm run deploy` | Pack and install into the store's plugin folder |
15
+ | `npm run link-store -- <store repo>` | Use the store's real types (writes `tsconfig.store.json`) |
16
+
17
+ The store's plugin folder (its `RUNTIME_PLUGINS_DIR`) comes from `znode.local.json` (`{ "pluginsDir": "…" }`,
18
+ git-ignored), or the `RUNTIME_PLUGINS_DIR` environment variable. After the first deploy, enable the theme for your
19
+ stores in that folder's `plugins.json` (`"enabled": true`, `"stores": ["<store code>"]`).
20
+
21
+ ## Where each customization goes
22
+
23
+ | You want to | Do it in | Example here |
24
+ | --- | --- | --- |
25
+ | Change colors, fonts, spacing | `src/styles/*.css`, settings, `next/font/google` | `theme.css`, `src/server/fonts.ts` |
26
+ | Wrap every page in your layout | Server slot `layout.root` in `src/server.tsx` | `src/server/ThemeLayout.tsx` |
27
+ | Add to or replace a store part | A slot in `src/browser.tsx` (names in `znode-plugin/types/extension-api.d.ts`) | `src/slots/AnnouncementBar.tsx`, `src/slots/ProductBadge.tsx` |
28
+ | Add a page-builder block | A widget in `src/browser.tsx` and `"widgets"` in `znode-package.json` | `src/widgets/Hero.tsx` |
29
+ | Add a page at a new URL | `serverPages` in `src/server.tsx` and `"serverPages"` in `znode-package.json` | `/__NAME__-welcome`, `src/server/WelcomePage.tsx` |
30
+ | Add your own API | `routes` in `src/server.tsx` | `GET /api/extensions/plugins/__NAME__/highlights` |
31
+ | Let the merchant configure it | `settingsSchema` in `znode-package.json` | `accentColor`, `announcement`, `showBadge` |
32
+ | Change labels | `src/i18n/labels.json` (next-intl namespaces) | `{ "Product": { "addToCart": "Add to bag" } }` |
33
+ | Use the store's components | `import { SearchBox } from "@znode/base-components/…"` in browser parts | needs `npm run link-store` for types |
34
+
35
+ Imports work as in a Next.js app: `next/image`, `next/link`, `next/navigation`, `next/font/google`, `react`. They use
36
+ the store's own copies at runtime (one React, the store's router and images config).
@@ -0,0 +1,7 @@
1
+ node_modules/
2
+ dist/
3
+ releases/
4
+ .build/
5
+ # this machine's links: the store repo's types and the store's plugin folder
6
+ tsconfig.store.json
7
+ znode.local.json
@@ -0,0 +1,22 @@
1
+ {
2
+ "name": "__NAME__",
3
+ "version": "1.0.0",
4
+ "private": true,
5
+ "type": "module",
6
+ "scripts": {
7
+ "dev": "znode dev .",
8
+ "build": "znode build .",
9
+ "check": "znode check .",
10
+ "pack": "znode pack .",
11
+ "deploy": "znode deploy .",
12
+ "link-store": "znode link-store"
13
+ },
14
+ "devDependencies": {
15
+ "@types/react": "19.2.13",
16
+ "@types/react-dom": "19.2.3",
17
+ "next": "16.1.6",
18
+ "react": "19.2.4",
19
+ "react-dom": "19.2.4",
20
+ "znode-plugin": "^0.1.0"
21
+ }
22
+ }
@@ -0,0 +1,11 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="1280" height="360" viewBox="0 0 1280 360">
2
+ <defs>
3
+ <linearGradient id="hero-bg" x1="0" y1="0" x2="1" y2="1">
4
+ <stop offset="0" stop-color="#1e3a8a"/>
5
+ <stop offset="1" stop-color="#2563eb"/>
6
+ </linearGradient>
7
+ </defs>
8
+ <rect width="1280" height="360" fill="url(#hero-bg)"/>
9
+ <circle cx="1080" cy="180" r="120" fill="none" stroke="#ffffff" stroke-opacity="0.25" stroke-width="28"/>
10
+ <path d="M0 360 L240 160 L400 280 L560 180 L820 360 Z" fill="#000000" fill-opacity="0.15"/>
11
+ </svg>
@@ -0,0 +1,26 @@
1
+ import type { IBrowserHost, IBrowserPlugin } from "znode-plugin/types/extension-api";
2
+ import { bindHost } from "./lib/host.js";
3
+ import { AnnouncementBar } from "./slots/AnnouncementBar.js";
4
+ import { ProductBadge } from "./slots/ProductBadge.js";
5
+ import { Hero, HERO_EDITOR } from "./widgets/Hero.js";
6
+
7
+ // __LABEL__, browser part: what renders in the store's pages (on the server first, then hydrated in the browser).
8
+ // Slots: wrap or replace a part of the store; the component gets the slot's props, and the store's own rendering as
9
+ // children (keep it, add to it, or replace it). Slot names: znode-plugin/types/extension-api.d.ts.
10
+ // Widgets: blocks for the page builder, with their settings.
11
+ // Server parts (layouts around pages, whole pages, API routes): server.tsx.
12
+
13
+ export default function setup(host: IBrowserHost): IBrowserPlugin {
14
+ bindHost(host);
15
+ return {
16
+ slots: {
17
+ // an announcement bar above the store's header
18
+ "layout.header": AnnouncementBar,
19
+ // a New badge on product cards
20
+ "product.card": ProductBadge,
21
+ },
22
+ widgets: {
23
+ __PASCAL__Hero: { render: Hero, ...HERO_EDITOR },
24
+ },
25
+ };
26
+ }
@@ -0,0 +1 @@
1
+ {}
@@ -0,0 +1,9 @@
1
+ import type { IBrowserHost } from "znode-plugin/types/extension-api";
2
+
3
+ // This package's browser-safe settings (settingsSchema keys with "browser": true), for its slots and widgets. Set once
4
+ // by setup (browser.tsx); module scope is per store on the server and per page in the browser.
5
+ export let settings: Record<string, unknown> = {};
6
+
7
+ export function bindHost(host: IBrowserHost) {
8
+ settings = host.settings;
9
+ }
@@ -0,0 +1,17 @@
1
+ import type { ReactNode } from "react";
2
+ import { inter } from "./fonts.js";
3
+
4
+ // Server slot layout.root: every store page, header to footer (children), in the theme's font and accent color. The
5
+ // store's body is a flex column whose main area grows, so this wrapper grows too and the footer stays at the bottom.
6
+
7
+ // a CSS value from settings, without what could end the declaration
8
+ const cssValue = (value: unknown) => String(value ?? "").replace(/[^#a-zA-Z0-9(),.% -]/g, "").trim();
9
+
10
+ export function ThemeLayout(props: { children?: ReactNode; settings: Record<string, unknown> }) {
11
+ const accent = cssValue(props.settings.accentColor);
12
+ return (
13
+ <div className={`__NAME__-layout ${inter.className}`} data-test-selector="divThemeLayout" style={accent ? ({ "--theme-accent": accent } as Record<string, string>) : undefined}>
14
+ {props.children}
15
+ </div>
16
+ );
17
+ }
@@ -0,0 +1,27 @@
1
+ import Image from "next/image";
2
+ import Link from "next/link";
3
+ import { getHighlights } from "./data.js";
4
+
5
+ // A whole page at a new URL, /__NAME__-welcome (server.tsx serverPages and znode-package.json "serverPages"): an async
6
+ // server component that awaits its data and renders into the page's HTML, inside the store's layout.
7
+
8
+ export async function WelcomePage(props: { storeCode: string }) {
9
+ const highlights = await getHighlights(props.storeCode);
10
+ return (
11
+ <section className="__NAME__-welcome" data-test-selector="divWelcomePage">
12
+ <Image src="/api/extensions/files/__NAME__-hero.svg" alt="" width={1280} height={360} priority className="__NAME__-hero__image" />
13
+ <h1 className="__NAME__-welcome__title">Welcome to __LABEL__</h1>
14
+ <ul className="__NAME__-welcome__list">
15
+ {highlights.map((item) => (
16
+ <li key={item.id} data-test-selector={`divHighlight${item.id}`}>
17
+ <strong>{item.title}</strong>
18
+ <span>{item.text}</span>
19
+ </li>
20
+ ))}
21
+ </ul>
22
+ <Link href="/" className="__NAME__-hero__button">
23
+ Start shopping
24
+ </Link>
25
+ </section>
26
+ );
27
+ }
@@ -0,0 +1,18 @@
1
+ // A mock API: the shape a real source (Znode, a CMS, an ERP) would answer with. Replace the body with the real call;
2
+ // the welcome page and the highlights route only depend on IHighlight.
3
+
4
+ export interface IHighlight {
5
+ id: number;
6
+ title: string;
7
+ text: string;
8
+ }
9
+
10
+ const MOCK: IHighlight[] = [
11
+ { id: 1, title: "Account pricing", text: "Your agreed prices on every product." },
12
+ { id: 2, title: "Fast reorder", text: "Past orders and saved lists, ready to add to the cart." },
13
+ { id: 3, title: "Order tracking", text: "See where every order is and download its invoice." },
14
+ ];
15
+
16
+ export async function getHighlights(_storeCode: string): Promise<IHighlight[]> {
17
+ return MOCK;
18
+ }
@@ -0,0 +1,5 @@
1
+ import { Inter } from "next/font/google";
2
+
3
+ // The theme's Google font, declared as in any Next.js app; the build downloads it into the package and a page loads it
4
+ // only when something on it uses the class.
5
+ export const inter = Inter({ subsets: ["latin"], weight: ["400", "600", "700"], display: "swap" });
@@ -0,0 +1,33 @@
1
+ import type { ReactNode } from "react";
2
+ import type { IPluginRouteContext, IPluginRouteRequest, IRuntimePlugin, IServerSlotContext } from "znode-plugin/types/extension-api";
3
+ import { getHighlights, IHighlight } from "./server/data.js";
4
+ import { ThemeLayout } from "./server/ThemeLayout.js";
5
+ import { WelcomePage } from "./server/WelcomePage.js";
6
+
7
+ // __LABEL__, server part: runs only on the store's server, never in the browser.
8
+ // serverSlots: server components around a part of a store page (layout.root = every page, header to footer)
9
+ // serverPages: whole pages at new URLs (list them in znode-package.json "serverPages" too)
10
+ // routes: your API, /api/extensions/plugins/__NAME__/<route>
11
+ // They may be async (fetch data, call an API) and use next/image, next/link and next/font/google.
12
+
13
+ async function highlights(_request: IPluginRouteRequest, context: IPluginRouteContext): Promise<{ store: string; items: IHighlight[] }> {
14
+ return { store: context.store.code, items: await getHighlights(context.store.code) };
15
+ }
16
+
17
+ const plugin: IRuntimePlugin = {
18
+ name: "__NAME__",
19
+ apiVersion: 1,
20
+ hooks: {},
21
+ routes: { highlights },
22
+ serverSlots: {
23
+ "layout.root": (props: { children?: ReactNode }, context: IServerSlotContext) => <ThemeLayout settings={context.settings}>{props.children}</ThemeLayout>,
24
+ },
25
+ serverPages: {
26
+ "/__NAME__-welcome": {
27
+ render: (_props, context) => <WelcomePage storeCode={context.store.code} />,
28
+ metadata: { title: "Welcome", description: "What __LABEL__ brings to this store." },
29
+ },
30
+ },
31
+ };
32
+
33
+ export default plugin;
@@ -0,0 +1,19 @@
1
+ import type { ReactNode } from "react";
2
+ import { settings } from "../lib/host.js";
3
+
4
+ // Slot layout.header: a bar above the store's header (children), text from the announcement setting. Empty setting:
5
+ // the store's header as it is.
6
+
7
+ export function AnnouncementBar(props: { children?: ReactNode }) {
8
+ const text = String(settings.announcement || "");
9
+ return (
10
+ <>
11
+ {text && (
12
+ <div className="__NAME__-announcement" data-test-selector="divAnnouncement">
13
+ {text}
14
+ </div>
15
+ )}
16
+ {props.children}
17
+ </>
18
+ );
19
+ }
@@ -0,0 +1,17 @@
1
+ import type { ReactNode } from "react";
2
+ import { settings } from "../lib/host.js";
3
+
4
+ // Slot product.card: a New badge on the store's product card (children) when the product's NewProduct attribute is
5
+ // true, unless the showBadge setting is off.
6
+
7
+ type IProduct = { attributes?: { attributeCode?: string; attributeValues?: string }[] };
8
+
9
+ export function ProductBadge(props: { children?: ReactNode; product?: IProduct }) {
10
+ const isNew = props.product?.attributes?.some((item) => item.attributeCode === "NewProduct" && item.attributeValues === "true");
11
+ return (
12
+ <div className="__NAME__-card">
13
+ {settings.showBadge !== false && isNew && <span className="__NAME__-badge">New</span>}
14
+ {props.children}
15
+ </div>
16
+ );
17
+ }
@@ -0,0 +1,21 @@
1
+ /* __LABEL__ styles: linked into every page of the stores the theme is enabled for, after the store's own CSS.
2
+ Target your own classes, or the store's markup through its data-test-selector attributes. */
3
+
4
+ .__NAME__-layout { flex: 1 0 auto; display: flex; flex-direction: column; width: 100%; }
5
+
6
+ .__NAME__-announcement { padding: 8px 16px; text-align: center; font-size: 14px; color: #fff; background: var(--theme-accent, #2563eb); }
7
+
8
+ .__NAME__-card { position: relative; }
9
+ .__NAME__-badge { position: absolute; top: 8px; left: 8px; z-index: 1; padding: 2px 8px; font-size: 12px; font-weight: 700; color: #fff; background: var(--theme-accent, #2563eb); border-radius: 2px; }
10
+
11
+ .__NAME__-hero { position: relative; margin: 24px 0; overflow: hidden; border-radius: 8px; background: #f3f4f6; }
12
+ .__NAME__-hero__image { display: block; width: 100%; height: auto; }
13
+ .__NAME__-hero__text { padding: 24px; }
14
+ .__NAME__-hero__heading { margin: 0 0 8px; font-size: 28px; font-weight: 700; }
15
+ .__NAME__-hero__button { display: inline-block; margin-top: 12px; padding: 10px 20px; color: #fff; font-weight: 600; background: var(--theme-accent, #2563eb); border-radius: 4px; }
16
+
17
+ .__NAME__-welcome { padding: 0 0 40px; }
18
+ .__NAME__-welcome__title { margin: 24px 0 16px; font-size: 32px; font-weight: 700; }
19
+ .__NAME__-welcome__list { display: grid; gap: 16px; margin: 0 0 24px; padding: 0; list-style: none; grid-template-columns: 1fr; }
20
+ @media (min-width: 768px) { .__NAME__-welcome__list { grid-template-columns: repeat(3, 1fr); } }
21
+ .__NAME__-welcome__list li { display: flex; flex-direction: column; gap: 4px; padding: 16px; border-top: 3px solid var(--theme-accent, #2563eb); background: #f9fafb; }
@@ -0,0 +1,44 @@
1
+ import Image from "next/image";
2
+ import Link from "next/link";
3
+
4
+ // __PASCAL__Hero: a page-builder block. HERO_EDITOR names it, gives its fields and the values a new block starts with;
5
+ // the merchant drops it on a page and fills them in. next/image and next/link are the store's own (its images config,
6
+ // its router). Render the same thing on the server and in the browser: no Date.now() or window during render.
7
+
8
+ type IHeroProps = { id?: string; heading?: string; text?: string; image?: string; buttonText?: string; buttonUrl?: string };
9
+
10
+ export function Hero(props: IHeroProps) {
11
+ return (
12
+ <section className="__NAME__-hero" data-test-selector={`divHero${props.id || ""}`}>
13
+ {props.image && <Image src={props.image} alt="" width={1280} height={360} className="__NAME__-hero__image" priority />}
14
+ <div className="__NAME__-hero__text">
15
+ {props.heading && <h2 className="__NAME__-hero__heading">{props.heading}</h2>}
16
+ {props.text && <p>{props.text}</p>}
17
+ {props.buttonText && props.buttonUrl && (
18
+ <Link href={props.buttonUrl} className="__NAME__-hero__button" data-test-selector="linkHero">
19
+ {props.buttonText}
20
+ </Link>
21
+ )}
22
+ </div>
23
+ </section>
24
+ );
25
+ }
26
+
27
+ export const HERO_EDITOR = {
28
+ label: "__LABEL__ Hero",
29
+ category: "Content",
30
+ fields: {
31
+ heading: { type: "text", label: "Heading" },
32
+ text: { type: "textarea", label: "Text" },
33
+ image: { type: "text", label: "Image URL" },
34
+ buttonText: { type: "text", label: "Button text" },
35
+ buttonUrl: { type: "text", label: "Button link" },
36
+ },
37
+ defaultProps: {
38
+ heading: "Made for your business",
39
+ text: "Tell buyers what makes this store worth their time.",
40
+ image: "/api/extensions/files/__NAME__-hero.svg",
41
+ buttonText: "Shop now",
42
+ buttonUrl: "/",
43
+ },
44
+ };
@@ -0,0 +1,7 @@
1
+ {
2
+ // tsconfig.store.json (this machine's, git-ignored) extends the znode-plugin preset and, once you run
3
+ // `npm run link-store -- <path to the store repo>`, the store's tsconfig.base.json: every @znode alias then resolves to
4
+ // the store's real source and types.
5
+ "extends": "./tsconfig.store.json",
6
+ "include": ["src", "znode-env.d.ts"]
7
+ }
@@ -0,0 +1,3 @@
1
+ // Types for image imports in the store's components (*.png, *.svg), as the webstore has them, for type checks of store
2
+ // files once the store is linked (npm run link-store).
3
+ /// <reference types="next/image-types/global" />
@@ -0,0 +1,43 @@
1
+ {
2
+ "name": "__NAME__",
3
+ "version": "1.0.0",
4
+ "kind": "theme",
5
+ "apiVersion": 1,
6
+ "label": "__LABEL__",
7
+ "publisher": "__PUBLISHER__",
8
+ "description": "__LABEL__: a store layout with its own font, an announcement bar, a New badge on product cards, a hero block for the page builder and a welcome page.",
9
+ "license": "proprietary",
10
+ "keywords": ["theme"],
11
+ "permissions": ["routes"],
12
+ "compatibility": { "webstore": ">=10.0.0" },
13
+ "build": {
14
+ "server": "src/server.tsx",
15
+ "browser": "src/browser.tsx"
16
+ },
17
+ "styles": ["src/styles/*.css"],
18
+ "assets": ["src/assets/*"],
19
+ "messages": "src/i18n/labels.json",
20
+ "widgets": ["__PASCAL__Hero"],
21
+ "serverPages": ["/__NAME__-welcome"],
22
+ "settingsSchema": {
23
+ "accentColor": {
24
+ "type": "string",
25
+ "label": "Accent color (CSS)",
26
+ "browser": true,
27
+ "default": "#2563eb",
28
+ "attribute": "ThemeAccentColor"
29
+ },
30
+ "announcement": {
31
+ "type": "string",
32
+ "label": "Announcement bar text (empty: no bar)",
33
+ "browser": true,
34
+ "default": "Free shipping on orders over $100"
35
+ },
36
+ "showBadge": {
37
+ "type": "boolean",
38
+ "label": "Show the New badge on product cards",
39
+ "browser": true,
40
+ "default": true
41
+ }
42
+ }
43
+ }