@bernierllc/changeset-manager

Pure changeset management utilities for versioning and changelog generation in monorepos.

Features

• Changeset Creation: Create and manage changeset files with proper formatting
• Version Bump Calculation: Calculate appropriate version bumps based on changesets
• Changelog Generation: Generate comprehensive changelogs from changeset data
• Workspace Integration: Read package versions from npm workspaces
• Breaking Changes Support: Handle breaking changes with proper versioning
• Real Filesystem Operations: No mocks - uses real filesystem for testing
• TypeScript Support: Full TypeScript support with strict typing

Installation

npm install @bernierllc/changeset-manager

Quick Start

import { ChangesetManager } from '@bernierllc/changeset-manager';

// Initialize with custom changesets directory
const changesetManager = new ChangesetManager('.changeset');

// Create a new changeset
const result = changesetManager.createChangeset({
  packages: ['@myorg/package-1', '@myorg/package-2'],
  bumpType: 'minor',
  summary: 'Add new feature to both packages'
});

// Read existing changesets
const changesets = changesetManager.readChangesets();

// Generate changelog
const changelog = changesetManager.generateChangelog(
  changesets.changesets,
  changesetManager.getPackageVersions('./')
);

API Reference

ChangesetManager

Constructor

new ChangesetManager(changesetsDir?: string, config?: Partial<ChangesetConfig>)

• changesetsDir: Directory to store changeset files (default: .changeset)
• config: Optional configuration object

Methods

createChangeset(options: ChangesetOptions): ChangesetResult

Create a new changeset entry.

const result = changesetManager.createChangeset({
  packages: ['@myorg/package-1'],
  bumpType: 'patch',
  summary: 'Fix critical bug',
  breaking: false,
  dependencies: ['@myorg/other-package'],
  dryRun: false
});

readChangesets(): ChangesetResult

Read all existing changeset files.

const result = changesetManager.readChangesets();
console.log(result.changesets); // Array of ChangesetEntry objects

deleteChangeset(changesetId: string): boolean

Delete a specific changeset file.

const deleted = changesetManager.deleteChangeset('changeset-id');

getPackageVersions(workspaceRoot: string): PackageVersion[]

Read package versions from npm workspace.

const packages = changesetManager.getPackageVersions('./');
console.log(packages); // Array of package information

calculateVersionBumps(changesets: ChangesetEntry[], packages: PackageVersion[]): Map<string, VersionBumpType>

Calculate version bumps for packages based on changesets.

const versionBumps = changesetManager.calculateVersionBumps(changesets, packages);
console.log(versionBumps.get('@myorg/package-1')); // 'major' | 'minor' | 'patch' | 'none'

generateChangelog(changesets: ChangesetEntry[], packages: PackageVersion[]): string

Generate changelog content from changesets and package information.

const changelog = changesetManager.generateChangelog(changesets, packages);
console.log(changelog); // Markdown formatted changelog

getConfig(): ChangesetConfig

Get current configuration.

const config = changesetManager.getConfig();

updateConfig(newConfig: Partial): void

Update configuration.

changesetManager.updateConfig({
  changelog: {
    title: 'Custom Changelog'
  }
});

Types

ChangesetOptions

interface ChangesetOptions {
  packages?: string[];           // Package names to include
  bumpType?: VersionBumpType;    // Version bump type
  summary?: string;              // Changeset summary
  breaking?: boolean;            // Is this a breaking change?
  dependencies?: string[];       // Dependent packages
  dryRun?: boolean;              // Don't write files
}

ChangesetEntry

interface ChangesetEntry {
  id: string;                    // Unique identifier
  summary: string;               // Changeset summary
  packages: string[];            // Affected packages
  bumpType: VersionBumpType;     // Version bump type
  timestamp: Date;               // Creation timestamp
  author?: string;               // Author information
  breaking?: boolean;            // Breaking change flag
  dependencies?: string[];       // Dependent packages
}

VersionBumpType

type VersionBumpType = 'major' | 'minor' | 'patch' | 'none';

Configuration

ChangesetConfig

interface ChangesetConfig {
  baseBranch: string;            // Git base branch
  access: 'public' | 'restricted'; // Package access level
  ignore: string[];              // Patterns to ignore
  changelog: {
    repo: string;                // Repository URL
    title: string;               // Changelog title
  };
  commit: {
    message: string;             // Commit message template
  };
  linked: string[][];            // Linked packages
  updateInternalDependencies: 'patch' | 'minor'; // Internal dependency updates
  ___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH: {
    onlyUpdatePeerDependentsWhenOutOfRange: boolean;
    updateInternalDependents: 'always' | 'out-of-range';
  };
}

Examples

Basic Usage

import { ChangesetManager } from '@bernierllc/changeset-manager';

const manager = new ChangesetManager();

// Create a simple changeset
const result = manager.createChangeset({
  packages: ['@myorg/core'],
  bumpType: 'patch',
  summary: 'Fix authentication bug'
});

if (result.success) {
  console.log('Changeset created successfully');
}

Breaking Changes

// Create a breaking changeset
const breakingResult = manager.createChangeset({
  packages: ['@myorg/api'],
  bumpType: 'major',
  summary: 'Remove deprecated API methods',
  breaking: true
});

Multiple Packages

// Update multiple packages
const multiResult = manager.createChangeset({
  packages: ['@myorg/core', '@myorg/utils', '@myorg/types'],
  bumpType: 'minor',
  summary: 'Add new utility functions to all packages'
});

Changelog Generation

// Generate a complete changelog
const changesets = manager.readChangesets();
const packages = manager.getPackageVersions('./');

const changelog = manager.generateChangelog(changesets.changesets, packages);
console.log(changelog);

Custom Configuration

const customManager = new ChangesetManager('.changeset', {
  changelog: {
    title: 'Release Notes',
    repo: 'https://github.com/myorg/myrepo'
  },
  commit: {
    message: 'chore: release packages'
  }
});

Testing

The package includes comprehensive tests that use real filesystem operations:

npm test

Tests cover:

• Changeset creation and validation
• File parsing and formatting
• Version bump calculations
• Changelog generation
• Configuration management
• Error handling

Error Handling

All methods return structured results with success flags and error arrays:

const result = manager.createChangeset({
  packages: [],
  summary: 'Test'
});

if (!result.success) {
  console.error('Errors:', result.errors);
  console.warn('Warnings:', result.warnings);
}

Best Practices

1. Use Descriptive Summaries: Write clear, concise summaries that explain the change
2. Group Related Changes: Include multiple packages in a single changeset when changes are related
3. Mark Breaking Changes: Always set breaking: true for API changes that require major version bumps
4. Review Before Publishing: Use dryRun: true to preview changes before applying them
5. Keep Changesets Focused: Each changeset should represent a single logical change

Contributing

This package follows the project's development standards:

• No mocks in tests - use real filesystem operations
• Comprehensive TypeScript typing
• Clear documentation and examples
• Proper error handling and validation

License

This package is licensed under the same terms as the parent project.