Auri

Organize package changes and releases in monolith repositories.

npm i -D auri
yarn add -D auri
pnpm add -D auri

Run commands:

npx auri
pnpm auri
yarn auri

Prerequisites

Auri is intentionally opinionated and intended for certain repositories:

• Single monolith repository (no monorepos)
• The package can be built and published with: npm run build && npm publish
• The package's package.json is in the repository root
• No pre-releases for patch/minor versions

Setup

Install Auri via NPM and update your repository.

1. Generate access tokens

You'll will need an NPM automation access token (classic) and a GitHub token with the following permissions:

• repo
• user:email

2. Create GitHub workflow

Create a GitHub workflow that runs on every push. The NPM token should be named NODE_AUTH_TOKEN and the GitHub token as AURI_GITHUB_TOKEN.

It is crucial that you setup actions/checkout@v3 with github.ref. Auri expects the current branch to be the target branch.

# .github/workflows/publish.yaml
name: "Publish package"
on: [push]

env:
  AURI_GITHUB_TOKEN: ${{secrets.AURI_GITHUB_TOKEN}}
  NODE_AUTH_TOKEN: ${{secrets.NODE_AUTH_TOKEN}}

jobs:
  publish-package:
    name: Publish package with Auri
    runs-on: ubuntu-latest
    steps:
      - name: Setup actions
        uses: actions/checkout@v3
        with:
          ref: ${{ github.ref }}
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 20
          registry-url: "https://registry.npmjs.org/"
          cache: "npm"
      - name: Prepare release
        run: npm run auri prepare ${{ github.ref_name }}
      - name: Publish package
        run: npm run auri publish ${{ github.ref_name }}

3. Configure permissions

Go to your repository's settings, and go to "Code and automation" > "Actions" > "General." Go to "Workflow permissions" and enable:

• "Read and write permissions"
• "Allow GitHub Actions to create and approve pull requests"

If your GitHub workflow have permissions defined, make sure content is set to write:

permissions:
  contents: write

Instructions

Basics

When you create a new pull request, run pnpm auri add to create a new changeset. Use add patch for patch changes and add minor for minor changes.

npx auri patch

This will create a new markdown file inside the .changesets directory. Write a concise summary of your changes. Each changeset should only include one change. A single PR may include multiple (or zero) changesets. Each changeset might look something like this:

Fix: Stop deleting operating system at midnight

When you merge this to main or master branch, Auri will detect your changes and create a new "Release request" as a pull request. When you merge this request, your package.json and CHANGELOG.md will be updated, and new version of your package will be published to NPM.

Versioned branches

Auri works by creating dedicated branches for each major version. For example, main will be for v3, v2 for v2, and v4 for experimental v4. This means you can maintain multiple major versions at once. Versioned branches be in the format of v<integer>.

Next versions

Whenever you create a versioned branch for a major version once above the version in main, it will publish packages with a "next" tag. These versions are your betas/alphas/prereleases and looks like 3.0.0-beta.16. In addition to patch and minor, you can also define major changes.

npx auri major

Once you merge the branch into main, Auri will automatically release a stable version. If you want to keep working on the previous version, make sure you create a versioned branch for it before merging.