Skip to content
Source
Sign inSign up
TanStack/schemas

Release on npm #48

Send to my agent
Closedtombeckenham opened this issue 0 comments
tombeckenhamcommented

Goal

Ship the release pipeline, not the first public versions. No npm publish / npm stage publish against the live registry as part of this issue.

Packages (keep names; all currently 404 on npm):

  • @modelschemas/client 0.1.0
  • @modelschemas/codegen 0.1.0
  • @modelschemas/vite 0.1.0
  • modelschemas (unscoped CLI) 0.1.0

Create / own the @modelschemas npm org. CLI stays unscoped.

Security posture (maximum)

  1. No long-lived npm token in GitHub. GitHub Actions authenticates to npm with OIDC trusted publishers.
  2. Stage-only trusted publisher permissions. CI may run npm stage publish only — not npm publish. A maintainer 2FA-approves each staged version on npmjs.com (or npm stage approve) before it is installable.
  3. After the one-time bootstrap, each package: Settings → Publishing access → Require two-factor authentication and disallow tokens.
  4. Provenance attestations are automatic on trusted-publisher GitHub Actions publishes (no --provenance flag).
  5. Publish job uses GitHub Environment npm (required reviewer + deployment-branch/tag limits). Workflow file is .github/workflows/publish.yml — npm trusted-publisher config must use that filename exactly.
  6. bun publish is not used for the CI publish step: Bun still talks token auth (NPM_CONFIG_TOKEN); OIDC + npm stage require npm CLI ≥ 11.15.0. Bun is used only to pack (it rewrites workspace:*).

Triggers

  • Push of a v* version tag (covers GitHub Releases that create that tag)
  • workflow_dispatch with dry_run defaulting to true (pack + verify, do not stage)

Not on every push to main. Package versions come from each package.json, not from the tag name; a tag v0.1.0 must match those versions or the job fails.

First-publish bootstrap (human, one-time)

npm's npm trust and npm stage publish both require the package to already exist. First 0.1.0 of each package cannot be staged.

  1. Create the @modelschemas org; enable 2FA on the publishing account.
  2. From a trusted laptop (npm login, 2FA): pack with bun scripts/npm-stage.ts --pack-dir <dir> --dry-run, then npm publish <tarball> --access public in order: client → codegen → vite → CLI. Approve each 2FA prompt.
  3. For each package: npm trust github <name> --file publish.yml --repo modelschemas/modelschemas --env npm --allow-stage-publish
  4. Disallow tokens on each package (step 3 in Security).
  5. GitHub repo Settings → Environments → npm: required reviewer; limit deploys to main / v* tags.

Ongoing releases: tag vX.Y.Z → Actions stages tarballs → 2FA-approve on npmjs.com Staged Packages (same order).

Out of scope

  • Actually publishing 0.1.0 to the registry
  • Changesets / auto version bumps
  • Renaming the npm scope
  1. tombeckenham closed this

Sign in to join this conversation.