whynot-design/PUBLISHING.md

Publishing @whynot/design

@whynot/design is published to the coulomb Gitea npm registry so consuming repos can pin a version (npm i @whynot/design@x.y.z) and track it at their own pace (WHYNOT-WP-0003). The git tag cut by make release (see DesignSystemIntroduction.md §6) is the version; publishing makes that version installable.

• Registry: https://forgejo.coulomb.social/api/packages/coulomb/npm/
• package.json publishConfig.registry already points npm publish here.
• lit is a peerDependency — consumers install it themselves so their bundler dedupes to a single lit instance.

The token (never commit it)

Publishing and installing @whynot/* need a Gitea package token. It is not stored in this repo — per .claude/rules/credential-routing.md, tokens are routed, not vended: a Gitea package token is operator/OpenBao-owned (railiance-platform). Obtain one from the operator and export it:

export NPM_AUTH_TOKEN=…        # Gitea package token; never paste into git/chat/logs

.npmrc (committed) references it via ${NPM_AUTH_TOKEN} — no secret lives in the file.

Publish (maintainer)

git checkout main && git pull --ff-only
make release VERSION=x.y.z      # bumps, cuts CHANGELOG, commits, tags  (§6)
git push --follow-tags origin main
npm publish                     # uses publishConfig.registry + NPM_AUTH_TOKEN

npm publish is outward and immutable — a published version cannot be silently replaced. Confirm the tag and npm pack --dry-run contents first.

Install (consumer)

Add an .npmrc to the consuming repo so the @whynot scope resolves to the registry, then install the package plus the lit peer:

# .npmrc
@whynot:registry=https://forgejo.coulomb.social/api/packages/coulomb/npm/
//forgejo.coulomb.social/api/packages/coulomb/npm/:_authToken=${NPM_AUTH_TOKEN}

npm i @whynot/design@x.y.z lit

The installed package carries the consumer-facing contract under ir/ (component contracts, tokens.json, exemplars) reachable via the ./ir/* export — that is what the drift check (WHYNOT-WP-0003 T05) reads to report changes between versions.