@kevinmaes/changesets-workflow

Interactive CLI tool to set up changesets-based release workflows in your repository.

Features

• Interactive prompts for workflow configuration
• Dry-run mode to preview changes before applying
• Status health check to validate installation and configuration
• Smart repair detection for broken installations
• Supports single-branch (main-only) and dual-branch (dev → main) strategies
• Configures workflows for both apps (Vercel, Netlify, etc.) and npm packages
• Automatic dev branch creation and setup for dual-branch workflows
• Generates GitHub Actions workflows for CI and releases
• Updates package.json with necessary scripts

Usage

Run in your project directory:

npx @kevinmaes/changesets-workflow

Preview changes first:

npx @kevinmaes/changesets-workflow --dry-run

Shows what files, scripts, branches, and packages would be affected without making any changes.

Check installation health:

npx @kevinmaes/changesets-workflow --status

Validates your changesets installation and provides actionable fixes for any issues found. Checks:

• Repository setup and configuration
• Workflow files (YAML validity)
• Branch configuration
• package.json integrity
• Changesets configuration
• GitHub Actions permissions guidance

The tool will guide you through:

1. Selecting your branching strategy (single or dual-branch)
2. Choosing your project type (app or npm package)
3. Selecting Node.js version for workflows
4. Creating dev branch (if dual-branch and doesn't exist)
5. Installing and configuring changesets

Branching Strategies

Single Branch (main-only)

Use when: You want immediate releases whenever a Version Packages PR is merged

Workflow:

1. Feature PR → main (with changeset)
2. Merge to main → Creates/updates "Version Packages" PR
3. Merge "Version Packages" PR → Immediately publishes to npm (if npm package) or deploys

Tradeoff: No control over release timing - every Version Packages PR merge triggers a release

Dual Branch (dev → main)

Use when: You want to control exactly when releases happen and batch multiple changes

Workflow:

1. Feature PR → dev (with changeset)
2. Merge to dev → Creates/updates "Version Packages" PR targeting dev
3. More features merge to dev → Updates existing "Version Packages" PR (batching)
4. When ready to release → Merge "Version Packages" PR to dev
5. Deploy workflow auto-triggers → Merges dev to main → Creates tag → Creates GitHub Release (→ npm publish)

Benefit: Full control over release timing - you decide when to merge the Version Packages PR. Once merged, everything happens automatically.

What Gets Created

The tool creates the following in your repository:

Single-branch strategy:

.changeset/
├── config.json          # Changesets configuration
└── README.md            # Instructions for your team

.github/workflows/
├── changeset-check.yml # Changeset validation workflow
└── release.yml         # Release workflow for version management

Dual-branch strategy:

.changeset/
├── config.json          # Changesets configuration
└── README.md            # Instructions for your team

.github/workflows/
├── changeset-check.yml # Changeset validation workflow
├── release.yml         # Release workflow (creates Version Packages PRs on dev)
└── deploy.yml          # Deploy workflow (merges dev→main, creates tag/release, publishes)

It also adds these scripts to your package.json:

{
  "scripts": {
    "changeset": "changeset",
    "version": "changeset version",
    "release": "pnpm build && changeset publish"  // npm packages only
  }
}

Requirements

• Git repository
• Node.js 18+
• pnpm package manager
• package.json file

After Installation

Smart Repair Detection

If your installation is broken or incomplete, the CLI will automatically detect missing files when you run the setup command. Instead of blocking with "already configured," it will:

• Show which files are missing or corrupt
• Offer to repair the installation
• Regenerate only the necessary files

You can also manually check installation health using --status flag.

For all workflows:

1. Review generated files
2. Commit and push changes
3. Create your first changeset: pnpm changeset

For dual-branch strategy:

Important: Set dev as the default branch in GitHub:

• Go to Settings → Branches → Default branch
• Change to dev

This ensures new PRs target dev by default.

For npm packages:

Add NPM_TOKEN to your repository secrets:

• Go to Settings → Secrets and variables → Actions
• Add new repository secret named NPM_TOKEN
• Value should be your npm access token

Resources

• Changesets Documentation
• Complete Workflow Guide

License

MIT