npm package: @goodiebag/nx-toolkit
Description: NX toolkit plugin with useful executors including release management and version tools
Latest version: 0.2.0

# @goodiebag/nx-toolkit

NX toolkit plugin providing useful commands and executors for development workflow in monorepos.

## Features

### 🌍 Global Commands
- **`nx versions`** - Display current versions of all packages in the workspace

### 🔧 Project Executors  
- **`release-please`** - Enhanced release workflow with branch creation and PR automation

## Installation

```bash
# Add to your workspace
pnpm add -D @goodiebag/nx-toolkit
```

## Usage

### Global Commands

Once installed, these commands are available globally in your workspace:

```bash
# Show package versions across the workspace
nx versions

# Show detailed version information
nx versions --verbose
```

### Project Executors

Add to your `project.json`:

```json
{
  "targets": {
    "release-please": {
      "executor": "@goodiebag/nx-toolkit:release-please",
      "options": {
        "createReleaseBranch": true,
        "specifier": "minor",
        "ensureCleanBase": false
      }
    }
  }
}
```

Then run:

```bash
# Enhanced release with branch creation
nx run my-project:release-please

# Dry run to preview changes
nx run my-project:release-please --dry-run

# CI/CD friendly
nx run my-project:release-please --yes --ensure-clean-base=false
```

## Commands

### `nx versions`

Displays current versions of all packages in the workspace by parsing NX release information.

**Options:**
- `--verbose` - Show additional information and help text

**Example output:**
```
📦 Current Package Versions:
==========================
nx-surrealdb          0.3.4
nx-toolkit            0.1.0
nx-rust               3.1.0
goodiebag             0.2.0
claude-code-toolkit   0.3.1
```

## Executors

### `release-please`

Enhanced release workflow that wraps the standard `nx release` command with automated branch creation and PR management.

**Parameters:**

| Parameter               | Type     | Default | Description                           |
| ----------------------- | -------- | ------- | ------------------------------------- |
| `specifier`             | string   | `minor` | Version bump type (major/minor/patch) |
| `dryRun`                | boolean  | `false` | Preview changes without applying      |
| `verbose`               | boolean  | `false` | Show detailed command output          |
| `skipPr`                | boolean  | `false` | Skip PR creation                      |
| `createReleaseBranch`   | boolean  | `true`  | Create release branch                 |
| `ensureCleanBase`       | boolean  | `true`  | Switch to clean base branch           |
| `yes`                   | boolean  | `false` | Non-interactive mode                  |
| `projects`              | string[] | -       | Target specific projects              |
| `groups`                | string[] | -       | Target release groups                 |

Plus all standard `nx release` parameters.

**Workflow:**

1. **Clean Base**: Switch to main branch and pull latest (if enabled)
2. **Branch Creation**: Create `release/project-name` branch  
3. **Release**: Run `nx release` with specified parameters
4. **PR Creation**: Create GitHub PR for the release

## Why This Plugin?

### Global Commands vs Project Executors

- **Commands** (`nx versions`) - Available globally once plugin is installed, great for information display
- **Executors** (`nx run project:release-please`) - Project-scoped, perfect for complex workflows that need configuration

### No Conflicts with Built-in NX

- `nx versions` - New command, doesn't override anything
- `nx release-please` - Project-scoped, doesn't interfere with built-in `nx release`
- `nx release` - Built-in NX release command remains unchanged

## Examples

```bash
# Check current versions before release
nx versions

# Release a specific package
nx run my-package:release-please --specifier=patch

# Preview release changes
nx run my-package:release-please --dry-run --verbose

# CI/CD release
nx run my-package:release-please --yes --skip-pr
```

## Development

### Building
```bash
# Build the plugin
nx build nx-toolkit
```

### Testing

**Executors** (work immediately after build):
```bash
# Test the versions executor
nx run goodiebag:versions

# Test the release-please executor (dry run)
nx run goodiebag:release-please --dry-run
```

**Commands** (require installation):
```bash
# Option 1: Install from local build
pnpm add -D file:./dist/packages/nx-toolkit

# Option 2: Install from npm (after publishing)
pnpm add -D @goodiebag/nx-toolkit

# Option 3: Add to nx.json plugins
# Add "@goodiebag/nx-toolkit" to the plugins array in nx.json

# Then test global command
nx versions
```

### Key Differences

- **Executors** - Reference local builds directly via project.json configuration
- **Commands** - Need plugin installation for NX to discover and register global commands

### Local Testing Workflow

1. Make changes to the plugin
2. Build: `nx build nx-toolkit`
3. Test executors: `nx run goodiebag:versions`
4. Test commands: Install locally then run `nx versions`