tuix-webcomponents 0.0.26 → 0.0.28

package/README.md

@@ -71,18 +71,37 @@ is enough. To start the request earlier, add the link to the document head:
 There is no `loadFonts()` helper any more: injecting the stylesheet from
 JavaScript reflowed the page once the face arrived.
 
+## Repository setup
+
+```bash
+npm install          # the package
+npm run docs:install # the documentation site, which is its own npm project
+```
+
+`docs/` carries its own `package.json` and lockfile, so a root `npm install`
+does not reach it, and `npm run docs:dev` and `npm run docs:build` fail until
+`docs:install` has run once. `scripts/build.sh` runs it for the same reason
+before it builds the site in CI. Nothing else needs a second install: the
+package build and Storybook run off the root dependencies, and `docs/` resolves
+`lit` and the component sources through them.
+
 ## Documentation
 
 The developer documentation site (Fumadocs, statically exported) lives in
 `docs/` as its own npm project:
 
 ```bash
-cd docs
-npm install
-npm run dev     # http://localhost:3000/en/developers
-npm run build   # static export into docs/dist
+npm run docs:install # once, and whenever docs/package-lock.json changes
+npm run docs:dev     # http://localhost:3000/en/developers
+npm run docs:build   # static export into docs/dist
 ```
 
+All three are `npm --prefix docs`, so the same commands run from inside `docs/`
+do the same thing — with one difference: `docs:install` is `npm ci`, a clean
+install of exactly what `docs/package-lock.json` pins. Adding or bumping a
+dependency therefore means an `npm install` inside `docs/`, to write the
+lockfile that `docs:install` then reproduces.
+
 It carries step-by-step integration guides for React/Next.js, Vue and Angular,
 and a page per component with live previews of every variant, in English and
 German. Pages are MDX files in `docs/content/docs/` (`*.mdx` English,
@@ -110,18 +129,14 @@ which is what `npm publish` ships (`files: ["dist"]`):
 
 The two steps are separate on purpose: `dist/` is also where the site is
 assembled, so the package build never writes it. Only the staging step does,
-and that runs inside `prepublishOnly` and `bin/publish.sh` — i.e. in the
-publish job, after the site has already been uploaded from its own job.
+and that runs in `bin/publish.sh` — i.e. in the publish job, after the site has
+already been uploaded from its own job.
 
 The steps behind it: `cem analyze` refreshes `custom-elements.json`,
 `scripts/build-react.ts` regenerates `src/react/`, `tsc -p tsconfig.publish.json`
 compiles both entry points with their declarations, `build:css` renders the
 tokens, and `tsc-esm-fix` adds the `.js` extensions Node's ESM resolver needs.
 
-`npm publish` re-runs build and staging through `prepublishOnly`, so a release
-cannot ship a stale `dist/`. `npm run publish:local` packs the same output into
-a linkable `local/` folder for trying it in another project.
-
 ## Releases
 
 Releases are automatic, from CircleCI. `bin/publish.sh` takes the newest
@@ -188,8 +203,8 @@ to it. `scripts/build.sh` is what assembles both into `dist/` for CI.
 Two builds, two folders, so neither clears the other: the site into `dist/`
 (`scripts/build.sh` — Storybook under `dist/storybook`, the docs export at the
 root) and the npm package into `package-build/` (`npm run build`). `dist/` is
-reused for the package only by `npm run stage:package`, which runs in the
-publish job.
+reused for the package only by `npm run stage:package`, which `bin/publish.sh`
+runs in the publish job.
 
 
 ## Tooling configs