← Docs View raw .md

Publishing @wisepunk/* to public npm

The portable runtime ships four packages — @wisepunk/core, @wisepunk/renderer-html, @wisepunk/renderer-svelte, @wisepunk/sdk — to the public npm registry (registry.npmjs.org), under the @wisepunk scope. Publishing is deliberate and gated — it never happens automatically. apps/web and @midl/optimizer are not published (private: true).

Scope history: the original @midl scope is taken on public npm by an unrelated package, so the packages are scoped @wisepunk (free, and aligned with the wisepunk.com brand).

How it's built (in-repo source vs published dist)

Each package keeps two exports:

  • top-level exports → src/*.ts — what the monorepo consumes (the app, vitest, svelte-check, HMR). No build step needed in-repo; zero build-order coupling.
  • publishConfig.exports → dist/* + publishConfig.access: "public", applied by pnpm pack/pnpm publish, so the published package is a Node-native-loadable build (bundled ESM + .d.ts), public on npm. Proven by tools/smoke-standalone.sh (CI): packs the tarballs, installs them in a throwaway dir, renders via plain node.

Builds: @wisepunk/core + @wisepunk/renderer-html + @wisepunk/sdk use tsup (single-file ESM bundle, deps external); @wisepunk/renderer-svelte uses @sveltejs/package. pnpm -r build builds all.

One-time setup (account + token)

  1. Own the @wisepunk scope on npm — register the npm user/org so the scope is yours (a free npm org named wisepunk covers public packages).
  2. Create an npm Automation access token (npmjs.com → Access Tokens → Generate → Automation). Automation tokens bypass 2FA — a normal publish token 403s in CI. Set it as the repo secret: gh secret set NPM_TOKEN --repo renewisepunk/midl.

Releasing (the deliberate steps)

  1. Describe the change — pnpm changeset (pick packages + semver bump). Commit the .changeset/*.md.
  2. Bump versions — pnpm changeset version. Commit, open a PR, merge to main.
  3. Publish — GitHub → Actions → "Release (@wisepunk/ → npm)" → Run workflow*, type publish. The job builds, runs the standalone smoke test, then pnpm changeset publish (auth = NPM_TOKEN).

Installing the published packages (consumers)

Public — no auth, no .npmrc:

npm install @wisepunk/renderer-html @wisepunk/core   # render anywhere
npm install @wisepunk/sdk                            # manage pages over the write API