@dimensional-innovations/tool-config

Universal configuration package for ESLint, Prettier, Stylelint, and semantic-release with automatic framework detection.

One package. Four tools. Zero configuration.

Stop juggling multiple config packages. This single package provides battle-tested configurations for ESLint, Prettier, Stylelint, and semantic-release that automatically detect your project's framework, environment, and TypeScript setup.

Why This Package?

Before:

npm install --save-dev \
  eslint @eslint/js eslint-config-airbnb eslint-plugin-react \
  prettier prettier-config-standard \
  stylelint stylelint-config-standard \
  semantic-release @semantic-release/git @semantic-release/changelog

# ...then configure each one individually

After:

npm install --save-dev @dimensional-innovations/tool-config

Features

• 🎯 Zero Configuration - Auto-detects your framework, environment, and TypeScript
• 🧰 Multi-Tool Support - ESLint, Prettier, Stylelint, semantic-release in one package
• ⚛️ 8+ Frameworks - React, Vue, Svelte, Solid, Astro, Angular, Vanilla JS, Node.js
• 📦 All-In-One - All plugins and parsers included as dependencies
• 🔧 Customizable - Override any setting while keeping smart defaults
• 🚀 Modern - ESLint 9+ flat config, latest tooling versions
• ✅ Battle-Tested - 369 tests with 100% coverage

Quick Start

Installation

npm install --save-dev @dimensional-innovations/tool-config

Or use the interactive CLI:

npx @dimensional-innovations/tool-config

Basic Usage

Create config files in your project root:

ESLint (eslint.config.js):

import { createConfig } from '@dimensional-innovations/tool-config'

export default await createConfig('eslint')

Prettier (prettier.config.js):

import { createConfig } from '@dimensional-innovations/tool-config'

export default createConfig('prettier')

Stylelint (stylelint.config.js):

import { createConfig } from '@dimensional-innovations/tool-config'

export default createConfig('stylelint')

semantic-release (release.config.js):

import { createConfig } from '@dimensional-innovations/tool-config'

export default createConfig('semantic-release')

That's it! The configs will automatically detect your framework and TypeScript setup.

Add npm Scripts

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint --fix .",
    "prettier": "prettier --check .",
    "prettier:fix": "prettier --write .",
    "style": "stylelint '**/*.css'",
    "style:fix": "stylelint '**/*.css' --fix"
  }
}

Supported Frameworks

Meta-frameworks: Next.js (→ React), Nuxt (→ Vue), SvelteKit (→ Svelte)

API Documentation

createConfig(tool, options)

The main factory function that creates configurations for any supported tool.

Parameters:

• tool (string, required): Tool name - 'eslint', 'prettier', 'stylelint', or 'semantic-release'
• options (object, optional): Configuration options

Common Options:

{
  framework: 'auto',      // 'auto' | 'react' | 'vue' | 'svelte' | etc.
  typescript: undefined,  // undefined (auto-detect) | true | false
  cwd: process.cwd()     // Working directory for detection
}

ESLint Options

await createConfig('eslint', {
  framework: 'auto', // Auto-detect or specify framework
  environment: 'auto', // 'auto' | 'browser' | 'node' | 'universal'
  typescript: undefined, // Auto-detect TypeScript
  ignore: [], // Additional ignore patterns
  rules: {} // Custom rule overrides
})

Example - Custom Rules:

export default await createConfig('eslint', {
  rules: {
    'no-console': 'off',
    'react/prop-types': 'warn'
  }
})

Example - Explicit Framework:

export default await createConfig('eslint', {
  framework: 'vue',
  typescript: true
})

Prettier Options

createConfig('prettier', {
  framework: 'auto',
  // Override any Prettier option
  semi: false,
  singleQuote: true,
  printWidth: 100
})

Example - Custom Settings:

export default createConfig('prettier', {
  printWidth: 120,
  tabWidth: 4,
  trailingComma: 'all'
})

Stylelint Options

createConfig('stylelint', {
  framework: 'auto',
  cssType: 'auto', // 'auto' | 'scss' | 'css' | { preprocessor, tailwind, modules }
  rules: {} // Custom rule overrides
})

Example - SCSS + Tailwind:

export default createConfig('stylelint', {
  cssType: {
    preprocessor: 'scss',
    tailwind: true
  }
})

semantic-release Options

createConfig('semantic-release', {
  preset: 'default', // 'default' | 'library' | 'monorepo'
  gitProvider: 'auto' // 'auto' | 'gitlab' | 'github' | 'bitbucket'
})

Example - Library Release:

export default createConfig('semantic-release', {
  preset: 'library',
  gitProvider: 'github'
})

Framework-Specific Guides

React

Auto-detected when:

• react or react-dom in dependencies
• next in dependencies (Next.js)

ESLint features:

• React hooks rules
• JSX best practices
• React 18+ features

Prettier features:

• JSX formatting
• Component style consistency

Stylelint features:

• CSS Modules support (:global, :local, composes)
• Tailwind CSS support (auto-detected)

Example:

// eslint.config.js - automatically detects React
export default await createConfig('eslint')

// prettier.config.js - automatically formats JSX
export default createConfig('prettier')

Vue

Auto-detected when:

• vue in dependencies
• nuxt in dependencies (Nuxt)

ESLint features:

• Vue 3 Composition API
• <script setup> support
• Template linting

Prettier features:

• SFC (Single File Component) formatting
• prettier-plugin-vue integration

Stylelint features:

• Scoped styles support
• Vue SFC style blocks

Example:

// stylelint.config.js - automatically handles .vue files
export default createConfig('stylelint')

// npm scripts
{
  "style": "stylelint '**/*.css' '**/*.vue'"
}

Svelte

Auto-detected when:

• svelte in dependencies
• @sveltejs/kit in dependencies (SvelteKit)

ESLint features:

• Svelte 5 runes support
• Component linting
• Reactive statements

Prettier features:

• Svelte component formatting
• prettier-plugin-svelte integration

Stylelint features:

• Component-scoped styles
• .svelte file support

TypeScript

Auto-detected when:

• typescript in devDependencies
• tsconfig.json exists

Features:

• Type-aware linting
• Strict type checking rules
• Import/export type syntax
• Works with all frameworks

Disable if needed:

export default await createConfig('eslint', {
  typescript: false // Force disable even if detected
})

CLI Tool

Interactive setup wizard for quick configuration:

npx @dimensional-innovations/tool-config

Features:

• Choose which tools to configure
• Auto-detects framework and TypeScript
• Creates config files automatically
• Adds npm scripts to package.json
• NEW: Automated CI/CD pipeline setup
• Supports dry-run mode

Options:

npx @dimensional-innovations/tool-config eslint          # Setup ESLint only
npx @dimensional-innovations/tool-config --all           # Setup all tools
npx @dimensional-innovations/tool-config --dry-run       # Preview without creating files
npx @dimensional-innovations/tool-config --ci gitlab     # Setup GitLab CI/CD
npx @dimensional-innovations/tool-config --ci github     # Setup GitHub Actions
npx @dimensional-innovations/tool-config --setup-ci      # Interactive CI setup
npx @dimensional-innovations/tool-config --help          # Show all options

CI/CD Integration:

When you select semantic-release in interactive mode, the CLI will automatically prompt you to setup CI/CD for automated releases. Or use the --ci flag to setup CI/CD directly:

# Interactive: prompts for provider if not detected
npx @dimensional-innovations/tool-config --setup-ci

# Direct: specify provider
npx @dimensional-innovations/tool-config --ci gitlab
npx @dimensional-innovations/tool-config --ci github
npx @dimensional-innovations/tool-config --ci bitbucket

# Combined: setup semantic-release + CI/CD
npx @dimensional-innovations/tool-config semantic-release --ci

The CLI will:

• Auto-detect your git provider (GitLab/GitHub/Bitbucket)
• Copy the appropriate CI/CD template
• Show environment variable configuration instructions
• Guide you through the setup process

CI/CD Setup

Ready-to-use CI/CD templates for GitLab CI, GitHub Actions, and Bitbucket Pipelines.

Automated Setup (Recommended)

The CLI tool can automatically setup CI/CD for you:

npx @dimensional-innovations/tool-config --ci gitlab  # Or github, bitbucket

This will:

• Auto-detect your git provider
• Copy the appropriate template
• Show configuration instructions

Manual Setup

Alternatively, copy templates manually from src/tools/semantic-release/templates/.

Each template includes:

• Lint Stage - Runs ESLint, Prettier, and Stylelint
• Test Stage - Runs tests with coverage reporting
• Release Stage - Automated semantic-release (main branch only)

GitLab CI

cp node_modules/@dimensional-innovations/tool-config/src/tools/semantic-release/templates/.gitlab-ci.yml .gitlab-ci.yml

Configure these CI/CD variables in GitLab:

• GL_TOKEN: GitLab Personal Access Token
• NPM_TOKEN: npm authentication token

GitHub Actions

mkdir -p .github/workflows
cp node_modules/@dimensional-innovations/tool-config/src/tools/semantic-release/templates/github-workflow.yml .github/workflows/ci.yml

Configure these secrets in GitHub:

• GITHUB_TOKEN: Automatically provided
• NPM_TOKEN: npm authentication token

Bitbucket Pipelines

cp node_modules/@dimensional-innovations/tool-config/src/tools/semantic-release/templates/bitbucket-pipelines.yml bitbucket-pipelines.yml

Configure this repository variable in Bitbucket:

• NPM_TOKEN: npm authentication token

See CI_SETUP.md for detailed configuration instructions.

Examples

See the examples/ directory for complete working examples:

• React App - TypeScript, CSS Modules
• Vue App - Composition API, Scoped Styles
• Svelte App - Svelte 5, Component Styles
• Solid App - TypeScript, Reactive Primitives
• Astro App - Multi-framework, TypeScript
• Angular App - TypeScript, Standalone Components
• Node Backend - Express, TypeScript
• Vanilla JS - Pure JavaScript, no framework

Each example includes all 4 tool configurations and npm scripts.

Advanced Usage

Monorepo Support

Use different configs per workspace:

// apps/frontend/eslint.config.js
export default await createConfig('eslint', {
  framework: 'react',
  typescript: true
})

// apps/backend/eslint.config.js
export default await createConfig('eslint', {
  framework: 'node',
  environment: 'node'
})

Custom Ignore Patterns

export default await createConfig('eslint', {
  ignore: ['dist/**', 'build/**', '**/*.generated.ts']
})

Environment-Specific Rules

const isDev = process.env.NODE_ENV === 'development'

export default await createConfig('eslint', {
  rules: {
    'no-console': isDev ? 'off' : 'error',
    'no-debugger': isDev ? 'warn' : 'error'
  }
})

Combining with Other Configs

import { createConfig } from '@dimensional-innovations/tool-config'
import customRules from './custom-rules.js'

const baseConfig = await createConfig('eslint')

export default [
  ...baseConfig,
  {
    files: ['**/*.js'],
    rules: customRules
  }
]

Ignoring Files

All tools automatically ignore common build outputs and generated files to prevent unnecessary linting and formatting. This happens automatically when you create a config - no manual setup required.

What Gets Ignored

Common directories (all tools):

• node_modules/ - Dependencies
• dist/, build/, out/ - Build outputs
• coverage/ - Test coverage reports
• .nyc_output/ - NYC coverage data

Framework build outputs (all tools):

• .next/ - Next.js
• .nuxt/, .output/ - Nuxt
• .svelte-kit/ - SvelteKit
• .vite/ - Vite cache
• .cache/, .parcel-cache/, .turbo/ - Build caches

Generated files (Prettier only):

• Lock files (package-lock.json, yarn.lock, pnpm-lock.yaml)
• CHANGELOG.md (auto-generated by semantic-release)

How It Works

ESLint: Uses runtime ignores array in flat config Stylelint: Uses runtime ignoreFiles property in config Prettier: Auto-generates .prettierignore file on first run

Customizing Ignore Patterns

ESLint - Add custom ignores:

export default await createConfig('eslint', {
  ignorePaths: ['generated/**', 'legacy/**']
})

Stylelint - Extend ignoreFiles:

export default createConfig('stylelint', {
  ignoreFiles: ['**/*.min.css', 'vendor/**']
})

Prettier - Edit .prettierignore file:

# Custom ignores
generated/
legacy/

Verifying Ignore Patterns

Check what files are being processed:

# ESLint
npx eslint --debug . 2>&1 | grep "Ignored"

# Stylelint
npx stylelint "**/*.css" --formatter verbose

# Prettier
npx prettier --check . --debug-check

Troubleshooting

Tools Processing Build Outputs

If you see errors about linting/formatting files in dist/, coverage/, or out/:

1. ESLint: Ignore patterns are applied automatically ✅
2. Stylelint: Ignore patterns are applied automatically ✅
3. Prettier: Check that .prettierignore was created. If not, re-run config creation or manually create the file.

Solution: If .prettierignore is missing, it will be auto-created next time you use the config. Or create it manually:

# Let Prettier generate it
node -e "import('@dimensional-innovations/tool-config').then(m => m.createConfig('prettier'))"

ESLint Not Detecting Framework

Ensure your package.json includes the framework dependency:

{
  "dependencies": {
    "react": "^18.0.0"
  }
}

Or explicitly specify:

export default await createConfig('eslint', {
  framework: 'react'
})

TypeScript Parsing Errors

Make sure typescript is installed:

npm install --save-dev typescript

Prettier Plugin Not Found

Install the required peer dependency:

npm install --save-dev prettier-plugin-svelte  # For Svelte
npm install --save-dev prettier-plugin-astro   # For Astro

Stylelint Not Linting .vue Files

Update your npm script to include .vue files:

{
  "scripts": {
    "style": "stylelint '**/*.css' '**/*.vue'"
  }
}

Config Not Updating After Framework Change

Delete node_modules/.cache and restart your editor:

rm -rf node_modules/.cache

Requirements

• Node.js: >= 22.12.0 (Node.js 22 LTS "Jod")
• npm: >= 10.0.0
• ECMAScript: ES2025 (ESM modules required)

Philosophy

This package follows these principles:

• Zero Config by Default - Works out of the box with sensible defaults
• Smart Detection - Automatically adapts to your project structure
• Fail Loudly - Errors for critical issues, warnings for quality improvements
• Framework Agnostic - No opinions about which framework you use
• Modern Standards - Uses latest tooling and ESLint flat config
• Comprehensive Coverage - 100% test coverage, battle-tested in production

Contributing

Contributions welcome! This package is built to be extensible.

To add a new framework:

1. Add detection logic in src/detectors.js
2. Create presets in src/tools/{tool}/presets/frameworks/
3. Add tests with 100% coverage
4. Update documentation

See IMPLEMENTATION_PLAN.md for architecture details.

License

MIT © DIMENSIONAL INNOVATIONS

Links

• npm package
• GitLab repository
• Issue tracker
• Changelog

Made with ❤️ by DIMENSIONAL INNOVATIONS