Publish

Publishing to npm

Workflow: Changesets

Every change needs a changeset before publish. No changeset = no publish.

1. Add a changeset (after making changes)

bunx changeset

Select: patch / minor / major, write summary. Creates .changeset/random-name.md.

2. Version bump (before publish)

bunx changeset version

Bumps package.json version + updates CHANGELOG.md.

3. Build

bun run build

bob build must exit 0. Check lib/ exists with module/ and typescript/ directories. Modern bob uses ESM-only output (no commonjs/ directory).

4. Publish

npm publish --access public

Use npm (not bun) for registry publish.

5. Tag + Release

git tag v1.2.3
git push --tags

Create GitHub release with CHANGELOG.md section as body.

6. Set up CI/CD (first publish only)

Add GitHub Actions workflows for automated checks and publish. Read the ci skill.

7. Submit to React Native Directory (optional)

If this is the first publish, submit to https://reactnative.directory for discoverability. Run /rn-lib-claude:directory or use the directory skill directly.

Pre-Publish Checklist

Run /publish command — it runs scripts/pre-publish.sh automatically.

Manual checks:

• bun run check passes (typecheck + lint + tests)
• bun run build passes
• lib/ contains module/ and typescript/ (modern bob uses ESM only, no commonjs/)
• exports map in package.json covers all public APIs
• All peer deps declared with correct version ranges
• At least one .changeset/*.md file exists
• No console.log in src/
• README.md documents every export
• Example app demos every export

Peer Dep Ranges

Use >= not ^ for all peer deps. Wide ranges prevent consumer conflicts. Mark reanimated/gesture-handler as optional if library only uses them in some components. See scaffold skill for the exact JSON — don't duplicate the values here.

Semver Rules

package.json files Field

Only ship what consumers need:

"files": ["lib/", "src/", "android/", "ios/", "README.md", "CHANGELOG.md"]

Never ship: example/, __tests__/, .husky/, .changeset/, node_modules/.

npm Auth

npm login
npm whoami  # verify

Set in CI via NPM_TOKEN secret:

- run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc

Common Issues

bob build fails with TS errors: Run bun run typecheck first, fix all errors.

Exports map missing: Consumer gets "package.json does not define exports" — add the exports field.

Peer dep version too tight: Consumer gets peer dep conflict — widen ranges with >=.

Forgotten changeset: bunx changeset will warn. CI should block publish without it.