znode-plugin 0.1.2 → 0.1.3

package/README.md

@@ -1,85 +1,382 @@
 # znode-plugin
 
-The SDK for Znode runtime plugins and themes: the `znode` command behind every project made with
-`create-znode-plugin`. A package is built on its own and runs in the webstore for the stores it is enabled for, with no
-fork of the store and no webstore rebuild.
+Build **Znode runtime themes and plugins**: change how a Znode webstore looks and behaves **without forking the store and
+without rebuilding it**. You write a small package, the SDK builds it, and the running webstore loads it.
 
-## Getting started
+---
 
-Start a new project with the recipe (any one of these, they are the same):
+## The story in 30 seconds
+
+Before, every customer change (a new header, a product card, a widget) meant editing the webstore's code. Each store
+became a fork, and every Znode upgrade meant re-applying those edits by hand.
+
+With runtime packages:
+
+```
+ your package (my-theme)                     the Znode webstore (unchanged)
+ ┌────────────────────────┐   npm run dev    ┌──────────────────────────────────────┐
+ │ src/styles/*.css       │ ───────────────▶ │ plugin folder (RUNTIME_PLUGINS_DIR)  │
+ │ src/browser.tsx (slots,│   build + copy   │   plugins.json  my-theme-1.0.0.*     │
+ │   widgets)             │                  │            │                         │
+ │ src/server.tsx (pages, │                  │            ▼ loaded at runtime       │
+ │   routes)              │                  │ every page of the stores it is on    │
+ └────────────────────────┘                  └──────────────────────────────────────┘
+```
+
+- **Theme**: the look of a store (colors, fonts, header, product card, widgets, pages).
+- **Plugin**: a feature (an integration, an API route, a cart rule).
+- One webstore serves many stores; each store gets the packages enabled for it.
+
+---
+
+## Quick start (5 minutes)
+
+**You need:** Node.js 20+, a checkout of the Znode webstore repo, and that webstore running locally (`npx nx dev webstore`).
+
+### 1. Create the project
 
 ```bash
-npm create znode-plugin@latest my-theme
-npx create-znode-plugin@latest my-theme
 npm init znode-plugin@latest my-theme
 ```
 
-It then asks two things, so have them ready:
+(`npm create znode-plugin@latest my-theme` and `npx create-znode-plugin@latest my-theme` do exactly the same.)
+
+It asks **one question: where your webstore is**. Answer it (it is what makes `npm run dev` work), even though the
+prompt offers Enter to skip:
+
+```
+Store path to connect (the store repo, with tsconfig.base.json), Enter to skip: D:\znode\webstore
+Store: D:\znode\webstore
+Plugin folder: D:\znode\runtime-plugins-store
+Created My Theme in D:\themes\my-theme
+Installing dependencies…
+linked D:\themes\my-theme\tsconfig.store.json to D:\znode\webstore\tsconfig.base.json (69 store aliases)
+```
+
+Give it the **root of the webstore repo** (not `apps/webstore`). The plugin folder is read from the store's own settings
+for you. *Why both? See [Why connect a store](#why-connect-a-store).*
 
-1. **The store path to connect**: the store repo, the folder with `tsconfig.base.json` at its root. The project gets
-   the store's real types from it (`znode link-store`).
-2. **The store's plugin folder**: where the webstore loads runtime packages from (its `RUNTIME_PLUGINS_DIR`, the folder
-   with `plugins.json`). Usually found for you in the store's `apps/webstore/.env.local` (or `.env`); asked only when
-   the store does not set it. `npm run dev` and `npm run deploy` copy your package there.
+> No webstore on this machine yet? Press Enter to skip. The project is still created, but `npm run dev` cannot deploy until
+> you connect it: `npm run link-store -- <webstore repo>` and a `znode.local.json` (see below).
 
-Then:
+### 2. Run it
 
 ```bash
 cd my-theme
 npm run dev
 ```
 
-and, with the webstore running in development mode, preview the theme in your browser only:
-`http://localhost:3000/api/extensions/preview?theme=my-theme`. The full walkthrough (every question, what to enter,
-skipping, scripts and CI, troubleshooting): [`create-znode-plugin`](https://www.npmjs.com/package/create-znode-plugin).
+This builds the package, copies it into the store's plugin folder, and does it again every time you save a file.
+
+### 3. See it in the store
+
+Open in your browser:
+
+```
+http://localhost:3000/api/extensions/preview?theme=my-theme
+```
+
+The store now shows your theme **in your browser only** (a cookie). Other shoppers still see the normal store.
+The starter theme adds an announcement bar above the header and a "New" badge on product cards, so you can see it working.
+
+| Preview link | What it does |
+| --- | --- |
+| `/api/extensions/preview?theme=my-theme` | turn on your theme, home page |
+| `/api/extensions/preview?theme=my-theme&to=/product/767` | turn it on and open a page |
+| `/api/extensions/preview` | turn the preview off (the store as it is) |
+| `/api/extensions/preview?list` | list the themes the store can see |
+
+### 4. Change something
+
+Edit `src/styles/theme.css`, for example:
+
+```css
+/* make every button in the store rounded */
+[data-test-selector^="btn"] { border-radius: 999px; }
+```
+
+Save. `npm run dev` rebuilds and redeploys; reload the page.
+
+### 5. Check before you ship
+
+```bash
+npm run check
+```
+
+Reviews the package like the marketplace does: manifest, permissions against the code, settings, sizes. Fix every error.
 
-To add the SDK to an existing package instead:
+### 6. Release
 
 ```bash
-npm install -D znode-plugin
+npm run pack       # releases/my-theme-1.0.0.zpkg.zip  (to hand to another store / environment)
+npm run deploy     # or: install once into the plugin folder of this machine
+```
+
+### 7. Turn it on for a store
+
+A deployed package is **off for every store** (preview only). To make it live, edit the plugin folder's `plugins.json`:
+
+```json
+{ "name": "my-theme", "enabled": true, "stores": ["MyStoreCode"] }
 ```
 
-## Connecting a project to a store
+Deploying again keeps these two fields.
 
-| What | How | Saved in |
+---
+
+## Why connect a store
+
+The project lives **outside** the webstore repo (its own git repo), so it needs two links to one store on your machine:
+
+| Link | Why | Saved in |
 | --- | --- | --- |
-| The store's types | `npm run link-store -- <store repo>` (`znode link-store <storeRepo> [dir]`) | `tsconfig.store.json` (git-ignored) |
-| The store's plugin folder | Answer the recipe's question, or write it yourself: `{ "pluginsDir": "D:\\znode\\runtime-plugins-store" }` | `znode.local.json` (git-ignored) |
+| **Store types** (the repo root) | Your code can import the store's own components and types (`@znode/base-components/...`) and TypeScript checks them against the real store code. Without it, those imports are red in the editor and `npm run build` cannot type-check them. | `tsconfig.store.json` |
+| **Plugin folder** (`RUNTIME_PLUGINS_DIR`) | Where `npm run dev` / `deploy` copies the built package, so the running webstore picks it up. | `znode.local.json` |
+
+Both files are **per machine** and git-ignored: each developer connects their own checkout.
+
+```bash
+npm run link-store -- D:\znode\webstore                              # (re)connect the store types
+echo { "pluginsDir": "D:\\znode\\runtime-plugins-store" } > znode.local.json   # set the plugin folder by hand
+```
+
+Run `link-store` again after the store adds or moves modules.
+
+---
+
+## What is in the project
+
+```
+my-theme/
+  znode-package.json     name, version, kind ("theme"), parent, settings, widgets, pages   ← the manifest
+  src/browser.tsx        slots and page-builder widgets (runs on the server first, then in the browser)
+  src/server.tsx         server-only: layouts around pages, pages at new URLs, API routes
+  src/slots/             AnnouncementBar (layout.header), ProductBadge (product.card)
+  src/widgets/Hero.tsx   a page-builder widget
+  src/server/            ThemeLayout (font on every page), WelcomePage (/my-theme-welcome)
+  src/styles/theme.css   CSS linked into every page
+  src/i18n/labels.json   text (labels) the theme changes
+```
+
+---
+
+## How do I ...? (examples)
+
+### Change colors and fonts
+
+```css
+/* src/styles/theme.css: the store's design tokens */
+html:root {
+  --primary: #4f9d39;
+  --link: #4f9d39;
+  --navigation-bar-bg: #3f5fb8;
+}
+```
+
+Google fonts, as in any Next.js app (`src/server/fonts.ts`), applied by the server slot `layout.root`:
+
+```ts
+import { Urbanist } from "next/font/google";
+export const urbanist = Urbanist({ subsets: ["latin"], weight: ["400", "700"], variable: "--font-urbanist" });
+```
 
-Both are per machine: each developer connects their own checkout. Run `link-store` again after the store adds or moves
-modules.
+### Restyle or hide part of a store page
+
+Every store element has a `data-test-selector`. Target it in CSS:
+
+```css
+/* hide the Job Name field at checkout */
+[data-test-selector="AdditionalInfoContainer"] form > div:has([data-test-selector="txtJobProjectHeadline"]) {
+  display: none;
+}
+```
+
+### Add something to a store part (a slot)
+
+A slot gets the store's own rendering as `children`: keep it, add to it, or replace it.
+
+```tsx
+// src/slots/ProductBadge.tsx
+import type { ReactNode } from "react";
+
+export function ProductBadge(props: { children?: ReactNode; product?: { isNew?: boolean } }) {
+  return (
+    <div className="my-theme-card">
+      {props.product?.isNew && <span className="my-theme-badge">New</span>}
+      {props.children /* the store's card, unchanged */}
+    </div>
+  );
+}
+```
+
+```tsx
+// src/browser.tsx
+export default function setup(host: IBrowserHost): IBrowserPlugin {
+  bindHost(host);
+  return { slots: { "product.card": ProductBadge } };
+}
+```
+
+**Slots:** `layout.header`, `layout.footer`, `header.search`, `product.card`, `product.image`, `product.variants`,
+`product.addToCart`, `product.layout`, `productList.layout`, `addToCart.notification`, `login.form`,
+`checkout.address`, `checkout.shippingOptions`. Server slots (in `server.tsx`): `layout.root`, `login.layout`, `login.page`.
+
+### Add a page-builder widget
+
+```tsx
+// src/widgets/Hero.tsx
+export function Hero(props: { heading?: string }) {
+  return <section className="my-theme-hero"><h2>{props.heading}</h2></section>;
+}
+export const HERO_EDITOR = {
+  label: "My Hero",
+  fields: { heading: { type: "text", label: "Heading" } },
+  defaultProps: { heading: "Welcome" },
+};
+```
+
+Register it in `browser.tsx` (`widgets: { MyThemeHero: { render: Hero, ...HERO_EDITOR } }`) and list
+`"widgets": ["MyThemeHero"]` in `znode-package.json`. Merchants then find it in the page builder.
+
+### Let the merchant change a value (settings)
+
+```json
+"settingsSchema": {
+  "announcement": { "type": "string", "label": "Announcement text", "browser": true, "default": "Free shipping" },
+  "hidePrices":   { "type": "boolean", "label": "Hide prices", "browser": true, "attribute": "HidePrices" }
+}
+```
+
+`"attribute"` reads the value from a Znode **global attribute** of the store (set in Znode Admin), on the server, per store.
+Read it in browser code with `settings` from `src/lib/host.ts`.
+
+### Change a text (label)
+
+```json
+// src/i18n/labels.json
+{ "Common": { "addToCart": "Add to Bag" } }
+```
+
+### Add a page at a new URL, or an API route
+
+```tsx
+// src/server.tsx
+serverPages: { "/my-theme-welcome": { render: () => <h1>Welcome</h1>, metadata: { title: "Welcome" } } },
+routes: { hello: async (_request, context) => ({ store: context.store.code }) },   // GET /api/extensions/plugins/my-theme/hello
+```
+
+List the page in `znode-package.json` (`"serverPages": ["/my-theme-welcome"]`); routes need `"permissions": ["routes"]`.
+
+### Build a theme on top of another theme
+
+```json
+"parent": "my-base-theme"
+```
+
+The parent's styles, labels, settings and slots apply first; yours on top.
+
+---
 
 ## Commands
 
-| Command | What it does |
+Run them with `npm run <name>` inside a project (the scripts call `znode … .`):
+
+| npm script | `znode` command | What it does |
+| --- | --- | --- |
+| `npm run dev` | `znode dev .` | build + deploy, again on every save |
+| `npm run build` | `znode build .` | type check, then bundles into `dist/` |
+| `npm run check` | `znode check .` | marketplace review (0 errors before you ship) |
+| `npm run pack` | `znode pack .` | build and zip into `releases/<name>-<version>.zpkg.zip` |
+| `npm run deploy` | `znode deploy .` | pack, then install into the plugin folder |
+| `npm run link-store -- <store repo>` | `znode link-store <repo> .` | connect the store's types |
+| | `npx znode install <zip> [pluginsDir]` | install a released zip into a store's plugin folder |
+| | `npx znode create <theme\|plugin\|widget\|content> <name>` | a minimal starter of another kind |
+
+The plugin folder is taken from: the command's argument, else the `RUNTIME_PLUGINS_DIR` environment variable, else
+`znode.local.json`.
+
+### `npm run dev` or `npm run deploy`?
+
+Both build the package and install it into the plugin folder. `dev` then keeps watching and installs again on every save;
+`deploy` installs once and exits.
+
+| Use | When |
 | --- | --- |
-| `znode build <dir>` | Type-check (with a `tsconfig.json`), then build the server and browser bundles into `dist/` |
-| `znode check <dir>` | Marketplace review: metadata, permissions against the code, settings, sizes |
-| `znode pack <dir>` | Build and zip into `releases/<name>-<version>.zpkg.zip` |
-| `znode install <zip\|dir> [storeDir]` | Install into the store's plugin folder (keeps the store's settings and stores) |
-| `znode deploy <dir> [storeDir]` | Pack, then install |
-| `znode dev <dir> [storeDir]` | Deploy, then again on every change under `src/` or to `znode-package.json` |
-| `znode link-store <storeRepo> [dir]` | Writes `tsconfig.store.json` so `@znode/*` imports get the store's real types |
-| `znode create <kind> <name> [dir]` | A minimal starter of a kind (theme, plugin, widget, content) |
-
-`storeDir` (the store's `RUNTIME_PLUGINS_DIR`): the argument, else the `RUNTIME_PLUGINS_DIR` environment variable, else
-`znode.local.json` (`{ "pluginsDir": "…" }`) in the folder the command runs in. With none of them, `deploy`, `install`
-and `dev` stop with `needs the store's plugin folder`.
-
-## After deploying
-
-- **Preview** (your browser only, webstore in development mode):
-  `/api/extensions/preview?theme=<name>`, `…&to=/<path>` to open a page, `/api/extensions/preview` to stop.
-  `/api/extensions/preview?list` lists the themes the store can see.
-- **Live for a store**: in the plugin folder's `plugins.json`, set the package's `"enabled": true` and add the store
-  codes to `"stores"`. Deploying again keeps those settings.
+| `npm run dev` | **While you write code** (the everyday command). Save, wait for `installed theme my-theme@…`, reload the page. You do not also run `deploy`. |
+| `npm run deploy` | **One install, no watching**: a fresh machine, after `git pull`, in a script or CI (it finishes; `dev` never does). |
+| `npm run pack` | **To hand the package to another store or environment**: a zip, installed there with `npx znode install`. |
+
+Like `next dev` and `next build`. Note: the store does not refresh an open page by itself; reload it after each install.
+
+---
+
+## Versions
+
+The version that counts is **`"version"` in `znode-package.json`**. It names the installed files
+(`my-theme-1.1.0.browser.mjs`, `my-theme-1.1.0.css`), so shoppers' browsers fetch new files instead of cached ones, and it
+is written to the package's entry in `plugins.json`. Installing keeps that entry's `enabled`, `stores` and `settings`.
+
+| Change | Bump | Example |
+| --- | --- | --- |
+| A fix, nothing new for merchants | patch | 1.1.0 → 1.1.1 |
+| New features (a slot, widget, page, setting), nothing removed | minor | 1.1.0 → 1.2.0 |
+| Breaking: a setting or widget field removed or renamed (saved pages break), the parent theme changed | major | 1.2.0 → 2.0.0 |
+
+**While developing, do not bump:** `npm run dev` re-installs the same version on every save, which is expected.
+
+**To release a version, by hand:**
+
+1. Edit `"version"` in `znode-package.json` (and the same in `package.json` to keep them equal; `npm version` changes only
+   `package.json`, which the store does not read).
+2. Check and pack:
+
+   ```bash
+   npm run check
+   npm run pack            # releases/my-theme-1.2.0.zpkg.zip
+   ```
+
+3. Install it: `npm run deploy` here (prints `installed theme my-theme@1.2.0 (was 1.1.0)`), or into another store:
+
+   ```bash
+   npx znode install releases/my-theme-1.2.0.zpkg.zip <that store's plugin folder>
+   ```
+
+4. Check `plugins.json`: `"version": "1.2.0"`, with `enabled`, `stores` and `settings` unchanged.
+5. Commit the version change and tag it:
+
+   ```bash
+   git commit -am "my-theme 1.2.0"
+   git tag my-theme@1.2.0
+   git push --tags
+   ```
+
+**Other numbers in the manifest:** `"apiVersion": 1` is the runtime API the package is written for (set by the SDK; do not
+change it), and `"compatibility": { "webstore": ">=10.14.0" }` says which webstore releases it supports.
+
+A parent theme and its child have their own versions: bump the one that changed. Old versions' files stay in the plugin
+folder after an upgrade; delete them by hand if you need the space.
+
+---
+
+## Troubleshooting
+
+| You see | Do this |
+| --- | --- |
+| `needs the store's plugin folder` | create `znode.local.json` (see [Why connect a store](#why-connect-a-store)) |
+| `@znode/...` imports are red | `npm run link-store -- <store repo>` |
+| Preview link returns 404 / no change | is the webstore running in **dev** mode? did `npm run dev` print `installed theme …` (no errors)? reload the page |
+| `installed …` but still no change | the package 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`) |
+| `MISSING_MESSAGE` for your label | put browser labels under a namespace the page sends, e.g. `Common` |
+| Theme shows for you but not shoppers | expected: enable it in `plugins.json` (step 7) |
+
+---
 
 ## Imports in a package
 
 | Import | At runtime |
 | --- | --- |
-| `react`, `react/jsx-runtime`, `next/image`, `next/link`, `next/navigation` | The store's own copies (one React, its router and images config) |
-| `next/font/google` | Built into the package: the font files are downloaded at build time |
-| `@znode/…` store modules the store publishes | The store's own modules, in browser parts |
+| `react`, `next/image`, `next/link`, `next/navigation`, `next-intl` | the store's own copies |
+| `next/font/google` | downloaded and built into the package |
+| `@znode/…` (store modules) | the store's own modules |
 
-Types for the package API (slots, widgets, server slots, server pages, routes, hooks): `znode-plugin/types/extension-api`.
+API types (slots, widgets, server pages, routes, hooks): `znode-plugin/types/extension-api`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "znode-plugin",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Build, check, pack and deploy Znode runtime plugins and themes: the SDK behind every create-znode-plugin project.",
   "license": "UNLICENSED",
   "type": "module",
@@ -28,5 +28,8 @@
     "rollup": "4.59.0",
     "typescript": "5.9.3"
   },
-  "publishConfig": { "registry": "https://registry.npmjs.org/", "access": "public" }
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
 }