semantic-release demo (TypeScript + npmjs.org)

A tiny TypeScript package that auto-versions and publishes to npmjs.org as @yura5o/semantic-release-demo on every push to main, driven by semantic-release.

Every commit message decides what (if anything) gets released:

| Commit type | Release | |--------------------------------------------|----------------| | fix: ... | patch (x.y.Z) | | feat: ... | minor (x.Y.0) | | feat!: ... / footer BREAKING CHANGE: | major (X.0.0) | | chore: ..., test: ..., ci: ... | no release |

What's in here

.
├── .github/workflows/release.yml   # CI — runs semantic-release on push
├── .husky/commit-msg               # local commitlint hook
├── .releaserc.json                 # semantic-release plugin pipeline
├── .npmrc                          # registry hint (NPM_TOKEN from env)
├── commitlint.config.cjs           # conventional-commits rules
├── src/index.ts                    # the actual package code
├── src/index.test.ts               # vitest tests
├── tsconfig.json
└── package.json                    # build + release scripts, publishConfig

Local setup

npm install
npm test
npm run build

npm run build uses tsup to produce ESM + CJS + .d.ts in dist/.

How the release pipeline works

On every push to main, .github/workflows/release.yml runs npx semantic-release, which executes the plugins from .releaserc.json in order:

1. commit-analyzer — reads commits since the last tag and decides bump type (uses the conventionalcommits preset).
2. release-notes-generator — builds release notes from those commits.
3. changelog — prepends notes to CHANGELOG.md.
4. npm — bumps package.json, builds the tarball, publishes to npmjs.org with provenance (OIDC-signed attestation via GitHub Actions).
5. git — commits the updated CHANGELOG.md + package.json back to main with [skip ci].
6. github — creates a GitHub Release with the tarball attached.

If no commits warrant a release, semantic-release exits cleanly — nothing is published.

One-time setup for your npmjs.org account (yura5o)

1. Create an npm automation token

• Log in at https://www.npmjs.com as yura5o.
• Go to Access Tokens → Generate New Token → Classic Token → type Automation.
• Copy the token (npm_...).

Automation tokens bypass 2FA, which is required for CI publishing.

2. Push this repo to GitHub

cd /Users/yurii/WebstormProjects/research/work/semver
git init
git add .
git commit -m "chore: bootstrap semantic-release demo"
git branch -M main
git remote add origin [email protected]:yura5o/semantic-release-demo.git
git push -u origin main

(Adjust the repo name/URL to whatever you create on GitHub. Also update repository.url in package.json if you change it.)

3. Configure the GitHub repo

• Settings → Secrets and variables → Actions → New repository secret
  • Name: NPM_TOKEN
  • Value: the npm_... token from step 1.
• Settings → Actions → General → Workflow permissions
  • Select Read and write permissions.
  • Check Allow GitHub Actions to create and approve pull requests.

4. First real release

Make any commit that triggers a release, for example:

git commit --allow-empty -m "feat: initial release"
git push

The workflow will:

• tag v1.0.0
• publish @yura5o/[email protected] to npmjs.org (with provenance)
• commit CHANGELOG.md back to main
• create a GitHub Release with the tarball attached

You'll see it at https://www.npmjs.com/package/@yura5o/semantic-release-demo.

Commit message convention

Uses Conventional Commits:

feat(api): add greet options
fix(greet): handle empty name
feat!: drop node 18 support

BREAKING CHANGE: minimum Node version is now 20.

Locally, the commit-msg husky hook runs commitlint so bad messages are rejected before they're pushed. Enable it once after npm install:

npx husky init   # or just: chmod +x .husky/commit-msg

Trying it out without publishing

Dry run against the current branch (no push, no publish):

export GITHUB_TOKEN=dummy      # dry-run just needs it to exist
export NPM_TOKEN=dummy
npx semantic-release --dry-run --no-ci

You'll see the computed next version and the release notes printed to the console.

Switching to a different registry later

Change publishConfig.registry in package.json and, if it's a scope-pinned registry, uncomment the relevant lines in .npmrc. Common options:

| Registry | URL | |-----------------------------|----------------------------------------------------| | npmjs.org (current) | https://registry.npmjs.org/ | | GitHub Packages | https://npm.pkg.github.com/ | | Self-hosted Verdaccio | https://verdaccio.your.domain/ | | JFrog Artifactory | https://artifactory.example.com/api/npm/npm/ |

For GitHub Packages specifically, you can drop NPM_TOKEN and use NPM_TOKEN: ${{ secrets.GITHUB_TOKEN }} directly in the workflow.