npm package: @scaffit/commitlint
Description: Commitlint configuration setup for conventional commits in Next.js, React, Vue, Angular, Svelte, Express, Fastify, Node.js projects
Author: Santosh Hanumaiah Ranganatha
Latest version: 1.0.5

# @scaffit/commitlint

Commitlint configuration setup for conventional commits.

## Features

- **Multi-framework support** - Next.js, React, Vue, Angular, Svelte, Express, Fastify, Node.js
- **Conventional commits** - Enforce consistent commit message format
- **Customizable rules** - Choose strictness level and specific rules
- **Husky integration** - Works seamlessly with Husky git hooks
- **Commit message validation** - Prevent bad commits from being made
- **Team consistency** - Ensure all team members follow same standards

## Installation

### Option 1: Using Scaffit CLI (Recommended)
```bash
# Add Commitlint scaffold (no installation needed!)
npx scaffit add commitlint
```

### Alternative: Global Installation
```bash
# Install CLI globally
npm install -g scaffit

# Add Commitlint scaffold
scaffit add commitlint
```

### Option 2: Direct npm package usage
```bash
# Install scaffold directly
npm install @scaffit/commitlint

# Use in your code
import { setupCommitlint, previewCommitlint } from '@scaffit/commitlint';

// Setup Commitlint with custom options
const result = await setupCommitlint({
  strictnessLevel: 'recommended',
  includeHuskyIntegration: true,
  projectRoot: './my-project'
});

// Preview changes before applying
const preview = await previewCommitlint({
  strictnessLevel: 'recommended',
  includeHuskyIntegration: true
});
```

**Note**: Both approaches require `@scaffit/core` to be installed (automatically handled).

## Configuration Options

- **Strictness level**: Choose between recommended, strict, or custom
- **Husky integration**: Add commit-msg hook to Husky
- **Custom rules**: Enable/disable specific commit rules
- **Framework**: Automatically detected (Next.js, React, Vue, Angular, Svelte, Express, Fastify, Node.js)

## Generated Files

### commitlint.config.js
Framework-specific commitlint configuration:

**Recommended (Default):**
```javascript
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat',
        'fix',
        'docs',
        'style',
        'refactor',
        'perf',
        'test',
        'chore',
        'ci',
        'build',
        'revert'
      ]
    ],
    'type-case': [2, 'always', 'lower-case'],
    'type-empty': [2, 'never'],
    'subject-case': [2, 'always', 'lower-case'],
    'subject-empty': [2, 'never'],
    'subject-full-stop': [2, 'never', '.'],
    'header-max-length': [2, 'always', 100]
  }
};
```

**Strict:**
```javascript
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat',
        'fix',
        'docs',
        'style',
        'refactor',
        'perf',
        'test',
        'chore',
        'ci',
        'build',
        'revert'
      ]
    ],
    'type-case': [2, 'always', 'lower-case'],
    'type-empty': [2, 'never'],
    'scope-case': [2, 'always', 'lower-case'],
    'subject-case': [2, 'always', 'lower-case'],
    'subject-empty': [2, 'never'],
    'subject-full-stop': [2, 'never', '.'],
    'header-max-length': [2, 'always', 72],
    'body-leading-blank': [2, 'always'],
    'body-max-line-length': [2, 'always', 100],
    'footer-leading-blank': [2, 'always'],
    'footer-max-line-length': [2, 'always', 100]
  }
};
```

**Custom:**
```javascript
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore']
    ],
    'type-case': [2, 'always', 'lower-case'],
    'type-empty': [2, 'never'],
    'subject-empty': [2, 'never']
  }
};
```

## Dependencies Added

- `@commitlint/cli` - Commitlint command-line interface
- `@commitlint/config-conventional` - Conventional commits configuration

## Package.json Scripts Added

- `commitlint` - Check commit messages
- `commitlint:edit` - Edit last commit message

## Conventional Commit Types

### Allowed Types
- `feat` - A new feature
- `fix` - A bug fix
- `docs` - Documentation only changes
- `style` - Changes that do not affect the meaning of the code
- `refactor` - A code change that neither fixes a bug nor adds a feature
- `perf` - A code change that improves performance
- `test` - Adding missing tests or correcting existing tests
- `chore` - Changes to the build process or auxiliary tools
- `ci` - Changes to CI configuration files and scripts
- `build` - Changes that affect the build system or external dependencies
- `revert` - Reverts a previous commit

## Usage Examples

### Check commit messages
```bash
npm run commitlint
```

### Edit last commit message
```bash
npm run commitlint:edit
```

### Manual validation
```bash
echo "feat: add new feature" | npx commitlint
```

## Commit Message Format

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

### Examples

**Good commits:**
```
feat: add user authentication
fix: resolve memory leak in data processing
docs: update API documentation
style: format code with prettier
refactor: extract common utility functions
perf: optimize database queries
test: add unit tests for user service
chore: update dependencies
ci: add automated testing workflow
build: configure webpack optimization
revert: revert "feat: add experimental feature"
```

**Bad commits:**
```
Add feature
Fixed bug
Update
WIP
```

## Husky Integration

If Husky is installed, commitlint will automatically add a commit-msg hook:

```bash
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx --no -- commitlint --edit $1
```

## Configuration

### Custom Rules

You can customize commitlint rules in `commitlint.config.js`:

```javascript
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore']
    ],
    'scope-case': [2, 'always', 'lower-case'],
    'subject-case': [2, 'always', 'sentence-case'],
    'header-max-length': [2, 'always', 50]
  }
};
```

### Rule Configuration

Each rule follows the format: `[level, applicable, value]`

- **Level**: `0` (disabled), `1` (warning), `2` (error)
- **Applicable**: `always` or `never`
- **Value**: The rule value (array, string, number, etc.)

## Framework-Specific Features

### Next.js
- Next.js specific commit types
- App Router related commits
- Next.js best practices

### React
- React component commits
- Hook-related commits
- React-specific patterns

### Vue
- Vue component commits
- Composition API commits
- Vue-specific patterns

### Angular
- Angular component commits
- Angular CLI commits
- Angular-specific patterns

### Svelte
- Svelte component commits
- SvelteKit commits
- Svelte-specific patterns

### Express/Fastify/Node.js
- API endpoint commits
- Middleware commits
- Server-side patterns

## Troubleshooting

### Common Issues

1. **Commit rejected**: Check commit message format
2. **Hook not running**: Ensure Husky is properly installed
3. **Rule conflicts**: Check rule configuration
4. **Type not allowed**: Add type to type-enum rule

### Debugging

```bash
# Check commitlint configuration
npx commitlint --print-config

# Validate specific message
echo "feat: test message" | npx commitlint

# Check installed rules
npx commitlint --help
```

## Best Practices

1. **Use conventional commits**: Follow the standard format
2. **Be descriptive**: Write clear, concise descriptions
3. **Use present tense**: "add feature" not "added feature"
4. **Keep it simple**: Avoid complex commit messages
5. **Team consistency**: Ensure all team members follow same rules

## Integration

### With Husky
- Automatically validates commits
- Prevents bad commits from being made
- Integrates with git hooks

### With CI/CD
- Can be run in CI pipelines
- Validates commit messages in PRs
- Ensures code quality standards

### With VS Code
Add to your VS Code settings.json:

```json
{
  "git.inputValidation": "on",
  "git.inputValidationLength": 100,
  "git.inputValidationSubjectLength": 50
}
```

## Next Steps

1. Customize `commitlint.config.js` for your needs
2. Set up Husky integration if not already done
3. Train team on conventional commit format
4. Add commitlint to CI/CD pipeline
5. Monitor commit quality and adjust rules as needed