@bfra.me/semantic-release
Version:
Semantic Release shareable configuration and plugins for bfra.me.
448 lines (442 loc) • 14 kB
TypeScript
import { LiteralUnion } from 'type-fest';
/**
* Core TypeScript types for semantic-release global configuration.
*
* This module provides comprehensive type definitions for semantic-release v23+
* configuration options, ensuring type safety and preventing runtime errors.
* All types are designed to provide maximum IntelliSense support while maintaining
* compatibility with the semantic-release ecosystem.
*
* @example
* ```typescript
* import type { GlobalConfig, BranchSpec, PluginSpec } from '@bfra.me/semantic-release'
*
* const config: GlobalConfig = {
* branches: ['main', { name: 'beta', prerelease: true }],
* plugins: ['@semantic-release/npm']
* }
* ```
*
* @see {@link https://semantic-release.gitbook.io/semantic-release/usage/configuration} for semantic-release configuration documentation
*/
/**
* Branch specification for semantic-release branches configuration.
*
* Defines a release branch with optional prerelease and maintenance configurations.
* Used to control which branches can trigger releases and how those releases are tagged.
*
* @example
* ```typescript
* // Production branch
* const mainBranch: BranchSpec = { name: 'main' }
*
* // Prerelease branch
* const betaBranch: BranchSpec = {
* name: 'beta',
* prerelease: true
* }
*
* // Maintenance branch
* const maintenance: BranchSpec = {
* name: 'maintenance',
* range: '1.x.x',
* channel: 'maintenance'
* }
* ```
*/
interface BranchSpec {
/**
* The name of the branch that should trigger releases.
*
* This should exactly match the Git branch name in your repository.
*
* @example 'main'
* @example 'develop'
* @example 'release/v2'
*/
name: string;
/**
* The range of versions to be released from this branch.
*
* Used primarily for maintenance releases to specify which major/minor
* versions this branch should handle. Follows semantic versioning patterns.
*
* @example '1.x.x' - Only 1.x patch releases
* @example '2.0.x' - Only 2.0 patch releases
* @example '+([0-9])?(.{+([0-9]),x}).x' - Pattern for multiple versions
*
* @see {@link https://semantic-release.gitbook.io/semantic-release/usage/configuration#branches} for patterns
*/
range?: string;
/**
* The npm distribution channel (dist-tag) to publish releases from this branch.
*
* Determines which npm dist-tag will be used when publishing packages.
* Set to `false` to skip npm publishing for this branch.
*
* @default The branch name for prerelease branches, 'latest' for production branches
*
* @example 'beta' - Publishes to @beta dist-tag
* @example 'next' - Publishes to @next dist-tag
* @example 'latest' - Publishes to @latest dist-tag (default for main)
* @example false - Skip npm publishing
*/
channel?: string | false;
/**
* Whether this branch should publish prereleases.
*
* When `true`, versions will be tagged as prereleases (e.g., 1.0.0-beta.1).
* When a string, uses that string as the prerelease identifier.
*
* @default false
*
* @example true - Uses branch name as prerelease identifier
* @example 'alpha' - Uses 'alpha' as prerelease identifier
* @example false - Production releases only
*/
prerelease?: boolean | string;
}
/**
* Branch configuration - flexible type accepting various branch specification formats.
*
* Can be:
* - A single branch name as string
* - A single branch specification object
* - An array of branch names and/or specification objects
*
* @example
* ```typescript
* // Single branch name
* const simple: BranchConfig = 'main'
*
* // Single branch spec
* const spec: BranchConfig = { name: 'main' }
*
* // Mixed array
* const complex: BranchConfig = [
* 'main',
* { name: 'beta', prerelease: true },
* 'develop'
* ]
* ```
*/
type BranchConfig = string | BranchSpec | readonly (string | BranchSpec)[];
/**
* Plugin specification type supporting both simple and configured plugins.
*
* Can be either:
* - A string representing the plugin package name
* - A tuple of [plugin name, plugin configuration options]
*
* This flexible type allows for both simple plugin inclusion and detailed
* plugin configuration within the same plugins array.
*
* @template TOptions - Type of the plugin configuration options object
*
* @example
* ```typescript
* // Simple plugin (uses defaults)
* const simple: PluginSpec = '@semantic-release/npm'
*
* // Configured plugin
* const configured: PluginSpec<NpmConfig> = [
* '@semantic-release/npm',
* { npmPublish: true, tarballDir: 'dist' }
* ]
*
* // Mixed usage in plugins array
* const plugins: PluginSpec[] = [
* '@semantic-release/commit-analyzer',
* ['@semantic-release/npm', { npmPublish: false }],
* '@semantic-release/github'
* ]
* ```
*/
type PluginSpec<TOptions = Record<string, unknown>> = string | readonly [string, TOptions];
/**
* Core semantic-release global configuration interface.
*
* This interface defines all the configuration options that can be used
* to configure semantic-release behavior. It provides full TypeScript
* support with comprehensive documentation and examples.
*
* @example
* ```typescript
* // Basic configuration
* const config: GlobalConfig = {
* branches: ['main'],
* plugins: ['@semantic-release/npm', '@semantic-release/github']
* }
* ```
*
* @example
* ```typescript
* // Advanced configuration
* const config: GlobalConfig = {
* branches: [
* 'main',
* { name: 'beta', prerelease: true },
* { name: 'alpha', prerelease: 'alpha' }
* ],
* repositoryUrl: 'https://github.com/owner/repo.git',
* tagFormat: 'v${version}',
* plugins: [
* '@semantic-release/commit-analyzer',
* ['@semantic-release/npm', { npmPublish: true }],
* '@semantic-release/github'
* ],
* dryRun: false,
* ci: true
* }
* ```
*/
interface GlobalConfig {
/**
* List of modules or file paths containing shareable configurations.
*
* If multiple shareable configurations are set, they will be imported
* in the order defined with each configuration option taking precedence
* over previous ones.
*
* @example
* ```typescript
* // Single shareable config
* extends: '@my-company/semantic-release-config'
*
* // Multiple configs (order matters)
* extends: [
* '@my-company/semantic-release-config-base',
* '@my-company/semantic-release-config-npm'
* ]
* ```
*/
extends?: string | readonly string[];
/**
* The branches on which releases should happen.
*
* Defines which Git branches should trigger releases and how those releases
* should be handled (production vs prerelease). Supports complex branching
* strategies including maintenance branches and multiple prerelease channels.
*
* @default ['+([0-9])?(.{+([0-9]),x}).x', 'master', 'main', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]
*
* @example
* ```typescript
* // Simple main branch only
* branches: ['main']
*
* // Main + prerelease branches
* branches: [
* 'main',
* { name: 'beta', prerelease: true },
* { name: 'alpha', prerelease: true }
* ]
*
* // Complex with maintenance
* branches: [
* 'main',
* { name: 'next', prerelease: true },
* { name: 'maintenance', range: '1.x.x' }
* ]
* ```
*/
branches?: BranchConfig;
/**
* The Git repository URL.
*
* Used to determine the repository for operations like creating releases
* and tags. Can be automatically detected from Git remotes or set via
* SEMANTIC_RELEASE_REPOSITORY_URL environment variable.
*
* @example 'https://github.com/owner/repo.git'
* @example 'git@github.com:owner/repo.git'
* @example 'https://gitlab.com/owner/repo.git'
*/
repositoryUrl?: string;
/**
* The Git tag format used to identify releases.
*
* Template string that defines how Git tags are formatted. The `${version}`
* placeholder is replaced with the actual version number.
*
* @default 'v${version}'
*
* @example
* ```typescript
* // Standard versioning
* tagFormat: 'v${version}' // Results in tags like v1.2.3
*
* // Monorepo package versioning
* tagFormat: '${name}@${version}' // Results in tags like my-package@1.2.3
*
* // Custom prefix
* tagFormat: 'release-${version}' // Results in tags like release-1.2.3
* ```
*/
tagFormat?: string;
/**
* List of plugins to use during the release process.
*
* Defines the plugins that will be executed during the semantic-release
* workflow. Each plugin can be a simple string (using defaults) or a
* tuple with configuration options.
*
* @default ['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']
*
* @example
* ```typescript
* // Basic plugin list
* plugins: [
* '@semantic-release/commit-analyzer',
* '@semantic-release/npm',
* '@semantic-release/github'
* ]
*
* // With plugin configurations
* plugins: [
* '@semantic-release/commit-analyzer',
* ['@semantic-release/npm', {
* npmPublish: true,
* tarballDir: 'dist'
* }],
* ['@semantic-release/github', {
* assets: ['dist/*.tgz']
* }]
* ]
* ```
*/
plugins?: readonly PluginSpec[];
/**
* Dry-run mode. Skip publishing, print next version and release notes.
*
* When enabled, semantic-release will analyze commits and generate release
* notes but will not actually publish anything. Useful for testing
* configurations and CI setups.
*
* @default false
*
* @example
* ```typescript
* // Enable dry-run for testing
* dryRun: true
*
* // Conditional dry-run based on environment
* dryRun: process.env.NODE_ENV !== 'production'
* ```
*/
dryRun?: boolean;
/**
* Set to false to skip Continuous Integration environment verifications.
*
* This allows for making releases from a local machine. When false,
* semantic-release will not verify that it's running in a CI environment.
*
* @default true
*
* @example
* ```typescript
* // Allow local releases
* ci: false
*
* // Standard CI-only releases
* ci: true
* ```
*/
ci?: boolean;
/**
* Set to true when the ci option is set to false.
*
* Internal property used by semantic-release to track CI mode state.
* Generally should not be set manually.
*
* @internal
*/
noCi?: boolean;
/**
* Global plugin configuration preset.
*
* Specifies a conventional commit preset that provides default rules
* for commit analysis and release note generation. Affects how commit
* messages are interpreted.
*
* @example
* ```typescript
* // Use Angular commit conventions
* preset: 'angular'
*
* // Use Conventional Commits standard
* preset: 'conventionalcommits'
*
* // Custom preset
* preset: '@my-company/commit-preset'
* ```
*/
preset?: LiteralUnion<'angular' | 'atom' | 'codemirror' | 'ember' | 'eslint' | 'express' | 'jquery' | 'jshint' | 'conventionalcommits', string>;
/**
* Additional configuration options that might be used by plugins.
*
* This allows for forward compatibility with new options and custom
* plugin configurations that are not part of the core semantic-release API.
*
* @example
* ```typescript
* {
* // Custom options for third-party plugins
* customPlugin: {
* apiKey: 'secret'
* },
* // Future semantic-release options
* experimentalFeature: true
* }
* ```
*/
[key: string]: unknown;
}
/**
* Enhanced configuration factory with validation and type inference.
*
* This module provides a comprehensive API for creating type-safe semantic-release
* configurations with runtime validation, developer-friendly factory functions,
* and support for complex configuration scenarios.
*
* @example
* ```typescript
* import {defineConfig} from '@bfra.me/semantic-release'
*
* // Basic usage with validation
* export default defineConfig({
* branches: ['main'],
* plugins: [
* '@semantic-release/commit-analyzer',
* '@semantic-release/release-notes-generator',
* '@semantic-release/npm',
* '@semantic-release/github'
* ]
* })
* ```
*/
/**
* Options for the defineConfig function.
*/
interface DefineConfigOptions {
/**
* Whether to validate the configuration at creation time.
* @default true
*/
validate?: boolean;
/**
* Environment context for configuration transformations.
*
* When specified, applies environment-specific optimizations and defaults:
* - `development`: Enables dry-run mode, debug logging, and development branches
* - `test`: Enables CI mode, dry-run, and test-specific settings
* - `staging`: Allows real releases with staging tags and debug logging
* - `production`: Production optimizations with minimal logging
*
* If not specified, environment is auto-detected from NODE_ENV, CI variables, and other indicators.
*
* @default 'production' (if auto-detection fails)
*/
environment?: 'development' | 'staging' | 'production' | 'test';
}
export type { BranchConfig as B, DefineConfigOptions as D, GlobalConfig as G, PluginSpec as P };