znode-plugin 0.1.1 → 0.1.2

package/README.md

@@ -4,11 +4,53 @@ The SDK for Znode runtime plugins and themes: the `znode` command behind every p
 `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.
 
+## Getting started
+
+Start a new project with the recipe (any one of these, they are the same):
+
+```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:
+
+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.
+
+Then:
+
 ```bash
-npm create znode-plugin@latest my-theme      # a new project (recommended)
-npm install -D znode-plugin                  # or add the SDK to an existing package
+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).
+
+To add the SDK to an existing package instead:
+
+```bash
+npm install -D znode-plugin
+```
+
+## Connecting a project to a store
+
+| What | How | 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) |
+
+Both are per machine: each developer connects their own checkout. Run `link-store` again after the store adds or moves
+modules.
+
+## Commands
+
 | Command | What it does |
 | --- | --- |
 | `znode build <dir>` | Type-check (with a `tsconfig.json`), then build the server and browser bundles into `dist/` |
@@ -21,7 +63,16 @@ npm install -D znode-plugin                  # or add the SDK to an existing pac
 | `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.
+`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.
 
 ## Imports in a package
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "znode-plugin",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Build, check, pack and deploy Znode runtime plugins and themes: the SDK behind every create-znode-plugin project.",
   "license": "UNLICENSED",
   "type": "module",