@sanity/semantic-release-preset NPM

@sanity/semantic-release-preset

Features

Usage

npm i -D @sanity/semantic-release-preset

If your package manager don't auto install peer dependencies make sure to install semantic-release:

npm i -D semantic-release

Setup the release config

Create a .releaserc.json:

{
  "extends": "@sanity/semantic-release-preset",
  "branches": ["main"]
}

The branches array is mandatory, and in most repositories you should put the default git branch here (main, or master if it's an older repository).

Optional: Configure prerelease branches

If you have stable releases going out from the git branch main, and want commits on the branch beta to result in only being installable with the npm dist-tag beta:

npm i package-name@beta

But not on:

npm i package-name # or npm i package-name@latest

Then use this config:

{
  "extends": "@sanity/semantic-release-preset",
  "branches": ["main", {"name": "beta", "prerelease": true}]
}

Minimal GitHub Release workflow

This is the bare minimum required steps to trigger a new release. This will push a new release every time an eliglible commit is pushed to git. Check the opinionated flow to see how to trigger releases manually. Create .github/workflows/ci.yml:

---
name: CI

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          # Need to fetch entire commit history to
          # analyze every commit since last release
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          cache: npm
          node-version: lts/*
      - run: npm ci
      - run: npm test --if-present
      # Branches that will release new versions are defined in .releaserc.json
      # @TODO uncomment after verifying with --dry-run we're ready to go
      # - run: npx semantic-release
      - run: npx semantic-release --dry-run
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}

It's important that you use --dry-run in the npx semantic-release command until you've verified that semantic-release is setup correctly and is able to detect your release branches and published version numbers. If you don't you may accidentally release a wrong version on npm, know that you can't simply unpublish accidents so it's best to be safe.

You need two secrets, secrets.GITHUB_TOKEN is always provided to GitHub actions, but if you try to --dry-run locally you'll need to create a token. It's easiest to just push commits and inspect the workflow output. You can add --debug to the npx semantic-release command to see more verbose logs if there's a tricky error.

The secrets.NPM_PUBLISH_TOKEN is provided on our GitHub org. If you're outside it you'll need to create it with auth-only 2FA and add it to the repository secrets.

If you're unable to make it work chances are your issue is documented in the `semantic-release` troubleshooting docs

Once you've confirmed with --dry-run that everything is looking good and semantic-release will perform the actions you expect it to, go ahead and edit .github/workflows/release.yml:

---
name: CI

on:
  # Build on pushes branches that have a PR (including drafts)
  pull_request:
  # Build on commits pushed to branches without a PR if it's in the allowlist
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          # Need to fetch entire commit history to
          # analyze every commit since last release
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          cache: npm
          node-version: lts/*
      - run: npm ci
      - run: npm test --if-present
      # Branches that will release new versions are defined in .releaserc.json
      - run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}

If this is on a brand new package that haven't published to npm yet, make a commit like this:

git add .github/workflows/release.yml
git commit -m "feat: initial release"
git push

If you're onboarding a package that already has a published version history:

git add .github/workflows/release.yml
git commit -m "fix: use semantic-release"
git push

Check the Release Workflow docs for more information.

Opinionated GitHub Release workflow

This flow runs a build task for linting and things that only need to run once.
Runs test, which runs a matrix of operating systems and Node.js versions.
FInally, runs release, if the workflow started from a workflow_dispatch, it is skipped on push.