npm package: @kevinmaes/changesets-workflow
Description: Interactive CLI tool to set up changesets-based release workflows
Author: Kevin Maes
Latest version: 0.5.2

# @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:

```bash
npx @kevinmaes/changesets-workflow
```

**Preview changes first:**

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

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

**Check installation health:**

```bash
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`:

```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](https://github.com/changesets/changesets)
- [Complete Workflow Guide](https://gist.github.com/kevinmaes/333b6e0c9e873872e543f742b2e54a7f)

## License

MIT