@oorabona/release-it-preset

Shareable release-it configuration and scripts for automated versioning, changelog generation, and package publishing — for solo and small-team JavaScript maintainers who want Keep a Changelog discipline without the ceremony of changesets or the hands-off philosophy of semantic-release.

Quick Start (30 seconds)

# Node `^22.21.0 || >=24.0.0`
pnpm add -D release-it@^21 @oorabona/release-it-preset

# Node `^20.19.0 || >=22.13.0 <22.21.0`
pnpm add -D release-it@^20 @oorabona/release-it-preset

# Node `^22.0.0 <22.13.0 || ^23.0.0`
pnpm add -D release-it@^19 @oorabona/release-it-preset

pnpm release-it-preset init --with-workflows

That's it. You now have:

• .release-it.json extending the default preset (auto-generated changelog from commits)
• A CHANGELOG.md with Keep a Changelog skeleton
• Release scripts in your package.json (pnpm release:patch, release:minor, release:major)
• A .github/workflows/release.yml that publishes via npm OIDC trusted publishing on tag push

Run a release:

pnpm release-it-preset validate    # pre-flight checks
pnpm release:minor                 # bump + commit + tag + push (CI publishes)

For monorepos: init auto-detects pnpm-workspace.yaml / package.json#workspaces and scaffolds per-package .release-it.json.

One-off (no install): pnpm dlx @oorabona/release-it-preset init --with-workflows

→ Full reference: docs/USAGE.md · Migration v0→v1 · Public API

Supply chain verification

Releases use npm OIDC provenance and, starting with v1.4.0, attach the npm registry tarball, SLSA L3 provenance, and a cosign keyless bundle to the GitHub release. See docs/VERIFY.md for copy-paste verification commands.

Why this preset?

Most release workflows fall into one of three traps: too much manual work (plain release-it, you assemble everything), too much ceremony (changesets, great for 5+ maintainers, heavy for one), or too much automation with too little control (semantic-release, hands-off by design and format).

@oorabona/release-it-preset occupies the productive middle ground for solo and small-team JavaScript package maintainers who want:

• Human-readable changelogs. Keep a Changelog format (Added/Changed/Deprecated/Removed/Fixed/Security) generated automatically from conventional commits — no manual entry writing, no machine-format diffs. [YANKED] markers in version headings are preserved transparently.
• OIDC publishing without CI plumbing. Import the reusable publish.yml workflow in three lines. OIDC trusted publishing with npm provenance ships on day one, no NPM_TOKEN secret required.
• Diagnostic confidence before release. Run release-it-preset doctor to surface every misconfiguration — git auth, npm auth, changelog hygiene, branch requirements — before anything breaks in CI.
• Recovery presets for the real world. Dedicated republish and retry-publish configs handle the scenarios other tools pretend don't happen.

Pick this preset if you maintain one or a few npm packages, write Keep a Changelog, deploy from GitHub Actions, and want pre-built OIDC publishing without adopting changesets or semantic-release's philosophy.

Do not pick this preset if you have a large monorepo with cross-package dependency management needs (use changesets) or if you want zero human involvement in versioning decisions (use semantic-release).

Ecosystem positioning

| Tool | Strength | When to prefer it | |---|---|---| | @oorabona/release-it-preset (this) | Keep a Changelog discipline + OIDC workflows + doctor CLI + recovery presets | Solo / small-team JS maintainer, human-curated changelogs, GitHub Actions CI | | release-it (plain) | Maximum flexibility, smallest opinion footprint | You want to assemble each piece yourself | | changesets | PR-driven versioning, fixed/linked package versions | 5+ maintainer monorepo, every change deserves explicit intent | | semantic-release | Fully-automated, zero human intervention | Branch-driven release pipelines, no human review of changelogs | | release-please | GitHub Release PR pattern, 20+ language strategies | Polyglot repos, GitHub-native PR-driven workflow | | @release-it-plugins/workspaces | Multi-package iteration + cross-pkg dep sync | Monorepo with bulk publish — composes with this preset |

Features

• One-command init — init --with-workflows scaffolds .release-it.json, CHANGELOG.md, package.json scripts, and a GitHub Actions publish workflow.
• Seven release configs — default, hotfix, manual-changelog, no-changelog, changelog-only, republish, retry-publish — each tuned for a specific scenario. → docs/USAGE.md#configurations
• Doctor command — pre-release diagnostics: branch state, publish workflow freshness, npm provenance readiness, SLSA attestation availability, peer-dep range, CHANGELOG validity, readiness score. → docs/USAGE.md#doctor
• OIDC trusted publishing — zero-config npm provenance via GitHub Actions OIDC; no NPM_TOKEN secret needed when using the reusable publish.yml workflow.
• Monorepo support — init auto-detects workspace manifests; GIT_CHANGELOG_PATH scopes changelog generation per package.
• Recovery flows — republish / retry-publish for the inevitable "first publish failed at npm step" moment.
• Smart dist-tag selection — pre-releases (-rc, -beta) auto-publish under non-latest tags.
• Conventional Commits aware — auto-generated [Unreleased] from commit history, with curatable manual edits preserved.
• Reusable GitHub workflows — publish.yml, hotfix.yml, republish.yml shipped as composable callables.
• TypeScript-first — DI pattern in scripts, fully testable (213 unit tests).

Installation & requirements

• Node.js ^20.19.0 || >=22.0.0 (Node 21 is not supported)

• Package manager: pnpm, npm, or yarn

• Peer dependency: release-it ^19.0.0 || ^20.0.0 || ^21.0.0. Choose release-it 21 on Node ^22.21.0 || >=24.0.0; release-it 20 on Node ^20.19.0 || >=22.13.0 <22.21.0; and release-it 19 on Node ^22.0.0 <22.13.0 || ^23.0.0, and when composing with @release-it-plugins/workspaces.

• release-it runtime:

  | release-it | Supported Node.js engines | | --- | --- | | 19 | ^20.12.0 || >=22.0.0 | | 20 | ^20.19.0 || ^22.13.0 || >=24.0.0 | | 21 | ^22.21.0 || >=24.0.0 |

• TypeScript: built with TypeScript 6; TypeScript 5+ projects are supported via the compiled ESM distribution

# Node `^22.21.0 || >=24.0.0`
pnpm add -D release-it@^21 @oorabona/release-it-preset

# Node `^20.19.0 || >=22.13.0 <22.21.0`
pnpm add -D release-it@^20 @oorabona/release-it-preset

# Node `^22.0.0 <22.13.0 || ^23.0.0`
pnpm add -D release-it@^19 @oorabona/release-it-preset

Try without installing:

pnpm dlx @oorabona/release-it-preset doctor    # health check on any repo
pnpm dlx @oorabona/release-it-preset init      # scaffold a new project

CHANGELOG

See CHANGELOG.md for all version history, or browse GitHub Releases.

Contributing & support

• CONTRIBUTING.md — Conventional Commits, branch prefixes, pre-PR checklist, testing conventions
• SUPPORT.md — where to ask questions, file bugs, and report security issues
• Discussions — Q&A, usage tips, ideas
• Issues — bugs + feature requests (use templates)
• SECURITY.md — vulnerability reporting (do NOT use public issues)

By participating you agree to abide by the Code of Conduct (Contributor Covenant 2.1).

License

MIT — see LICENSE.