Shared commitlint configuration with Linear integration and enhanced conventional commits support.

This package provides a comprehensive commitlint configuration that enforces commit message standards with enhanced features including Linear issue validation, automatic scope detection from pnpm workspaces, and interactive commit prompts.

• Linear Integration: Validates issue states and references through Linear API
• Smart Issue References: Supports Linear's magic keywords for automatic issue linking
• Extended Commit Types: Comprehensive set of commit types beyond conventional commits
• Interactive Prompts: Rich guided commit message creation
• Multiple Scopes: Support for comma-separated scopes
• Workspace Integration: Automatic scope detection from pnpm workspaces
• Strict Validation: Comprehensive rules for consistent formatting

See GUIDE.md documentation for details and examples on writing great commit messages with this config.

• Installation
• Quick Start
• Configuration
• Linear Integration
• Commit Types
• Scopes
• Development
• Troubleshooting
• API Reference

• Node.js ≥ 20.0.0
• pnpm package manager
• Git repository

# Install the configuration package
pnpm add -D @lottiefiles/commitlint-config

# Install commitlint CLI (if not already installed)
pnpm add -D @commitlint/cli

Create commitlint.config.mjs in your project root:

import { createConfig } from '@lottiefiles/commitlint-config';

export default createConfig({
  // Required: Linear team/project prefixes
  issuePrefixes: ['WEB', 'CRE'],
  
  // Optional: Enable Linear validation (defaults to 'auto')
  linearEnabled: true,
  
  // Optional: Allowed Linear issue states (defaults to ['started'])
  linearIssueStates: ['started', 'completed'],
});

# Install husky
pnpm add -D husky

# Initialize husky
pnpm exec husky install

# Add commit-msg hook
pnpm exec husky add .husky/commit-msg 'pnpm commitlint --edit $1'

Add to your package.json:

{
  "lint-staged": {
    "*": "pnpm commitlint --edit"
  }
}

Once configured, commitlint will automatically validate your commit messages:

# Valid commit
git commit -m "feat(auth): add OAuth2 authentication"

# Invalid commit (will be rejected)
git commit -m "Add new feature"  # Missing type format

# Set your Linear API key
export LINEAR_API_KEY="lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Commit with Linear issue reference
git commit -m "feat(auth): implement SSO login

Add single sign-on authentication with SAML support.
Includes proper error handling and user feedback.

Closes WEB-123"

For guided commit creation, use with commitizen:

# Install commitizen globally
npm install -g commitizen

# Use interactive prompts
git cz

import { createConfig } from '@lottiefiles/commitlint-config';

export default createConfig();

import { createConfig } from '@lottiefiles/commitlint-config';

export default createConfig({
  // Linear team prefixes (required for Linear integration)
  issuePrefixes: ['WEB', 'CRE', 'DEVOP'],
  
  // Linear API configuration
  linearEnabled: true,  // or 'auto' or false
  linearApiKey: process.env.LINEAR_API_KEY,
  linearIssueStates: ['started', 'completed'],
  
  // Custom scopes (overrides pnpm workspace detection)
  scopes: ['api', 'web', 'mobile', 'docs'],
});

1. Get Linear API Key:

   • Go to Linear Settings → API
   • Create a new API key
   • Set as environment variable: LINEAR_API_KEY=lin_api_xxx...

2. Configure Issue Prefixes:

   export default createConfig({
     issuePrefixes: ['WEB', 'CRE'], // Your Linear team keys
   });

The configuration validates:

• Issue exists in Linear
• Issue is in allowed states (default: ['started'])
• Reference uses valid action keywords

Linear magic keywords for automatic issue linking:

git commit -m "feat(auth): implement OAuth2 login

Add OAuth2 authentication with Google and GitHub providers.
Includes token refresh and proper error handling.

Closes WEB-123
Refs WEB-124"

By default, scopes are automatically detected from your pnpm-workspace.yaml:

packages:
  - 'packages/auth'
  - 'packages/api'
  - 'packages/web'

Valid scopes: auth, api, web

Override automatic detection:

export default createConfig({
  scopes: ['frontend', 'backend', 'mobile', 'docs'],
});

Use comma-separated scopes for cross-cutting changes:

git commit -m "feat(auth, api): implement user session management"

# Install dependencies
pnpm install

# Build TypeScript to JavaScript
pnpm build

# Build in watch mode
pnpm dev

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test --watch

# Run specific test file
pnpm test examples.test.ts

# Print resolved configuration
pnpm print-config

# Test commit message
echo "feat: add new feature" | pnpm commitlint

# Test with specific config
echo "feat(scope): message" | pnpm commitlint --config ./commitlint.config.mjs

1. Link Package Locally:

   # In this package directory
   pnpm link --global
   
   # In your test project
   pnpm link --global @lottiefiles/commitlint-config

2. Test Changes:

   # Make changes to src/
   pnpm build
   
   # Test in your project
   echo "feat: test message" | pnpm commitlint

1. Edit Local Plugin (src/local-plugin.ts):

   const myCustomRule: SyncRule = (parsed, when = 'always') => {
     // Your validation logic
     return [isValid, errorMessage];
   };
   
   export default {
     rules: {
       'my-custom-rule': myCustomRule,
       // ... existing rules
     },
   } satisfies Plugin;

2. Add to Configuration (src/define-config.ts):

   rules: {
     'my-custom-rule': [RuleConfigSeverity.Error, 'always'],
     // ... existing rules
   }

Problem: Linear API key must be available when linearEnabled is true

Solutions:

1. Set environment variable: export LINEAR_API_KEY="lin_api_xxx..."
2. Pass directly in config: linearApiKey: "lin_api_xxx..."
3. Disable Linear: linearEnabled: false

Problem: Valid-looking commits are rejected

Debug Steps:

1. Check exact error message: pnpm commitlint --verbose
2. Verify commit type is in allowed list
3. Ensure scope is kebab-case: feat(user-auth): ...
4. Check Linear issue exists and is in correct state

Problem: Scope not recognized in monorepo

Solutions:

1. Verify pnpm-workspace.yaml is properly configured
2. Use custom scopes: scopes: ['your', 'custom', 'scopes']
3. Check scope format is kebab-case

# Print full configuration
pnpm commitlint --print-config

# Verbose error output
echo "invalid message" | pnpm commitlint --verbose

# Test Linear API connection
curl -H "Authorization: Bearer $LINEAR_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.linear.app/graphql \
     -d '{"query":"{ viewer { id name } }"}'

1. Check Configuration: Ensure all required options are set
2. Verify Environment: Check Node.js version and dependencies
3. Test Incrementally: Start with basic config, add features gradually
4. Review Examples: See GUIDE.md for comprehensive examples

Creates a commitlint configuration with the specified options.

• options (optional): Configuration options object

• UserConfig: Complete commitlint configuration object

interface Options {
  issuePrefixes?: string[];
  linearApiKey?: string;
  linearEnabled?: 'auto' | boolean;
  linearIssueStates?: string[];
  scopes?: string[];
}

Array of all supported commit types.

Array of all supported Linear reference action keywords.