Kubit ESLint Configuration

A comprehensive and opinionated ESLint configuration package for TypeScript and React projects

Designed to enforce best practices, code quality, and accessibility standards.

Installation • Quick Start • Configuration • Migration Guide • Documentation • Contributing

---

✨ Features

• 🔧 Zero Configuration: Works out of the box with sensible defaults
• ⚛️ React Support: Complete React and JSX rules with accessibility (a11y) checks
• 🔷 TypeScript First: Full TypeScript support with strict type checking
• 🎨 Prettier Integration: Seamless integration with Prettier for code formatting
• 🧪 Jest Integration: Pre-configured Jest rules for testing environments
• ♿ Accessibility: Comprehensive a11y rules for inclusive web development
• 🌐 Browser Compatibility: Optional browser compatibility checking
• 📦 Import Management: Smart import sorting and organization
• 🔍 Code Quality: Advanced rules for code complexity and best practices

📋 Requirements

• Node.js: >= 20.19.0 (recommended: 22.x)
• pnpm: >= 9.0.0 (recommended: 10.29.2)
• ESLint: >= 10.0.0

📦 Installation

Install the package and its peer dependencies:

# Using pnpm (recommended)
pnpm add -D eslint eslint-config-kubit

# Using npm
npm install --save-dev eslint eslint-config-kubit

# Using yarn
yarn add --dev eslint eslint-config-kubit

Upgrading from v1.x?

See the Migration Guide for detailed instructions on upgrading to v2.0 with ESLint 10 support.

🚀 Quick Start

Basic Usage

Create an eslint.config.js file in your project root:

const eslintConfigKubit = require("eslint-config-kubit");

module.exports = eslintConfigKubit();

That's it! You now have a fully configured ESLint setup with TypeScript, React, and accessibility support.

Advanced Configuration

For more control over the configuration:

const eslintConfigKubit = require("eslint-config-kubit");
const path = require("path");

module.exports = eslintConfigKubit({
  // TypeScript configuration
  tsConfigPath: path.resolve(__dirname, "./tsconfig.json"),

  // Enable browser compatibility checks
  checkBrowserCompatibility: true,
  browserList: [
    "> 0.5%",
    "last 2 versions",
    "Firefox ESR",
    "not dead",
    "iOS >= 10",
    "Safari >= 10",
    "Edge >= 15",
  ],

  // Custom import rules
  noIndexImportConfig: {
    aliases: {
      "@/types": "./src/types/*",
      "@/components": "./src/components/*",
      "@/utils": "./src/utils/*",
    },
  },

  // Restrict specific imports
  noRestrictedImportsConfig: {
    paths: ["lodash", "moment"],
  },

  // Additional global variables
  globals: {
    myGlobalVar: "readonly",
  },
});

⚙️ Configuration Options

Option	Type	Default	Description
isReact	boolean	true	Enable React-specific rules and plugins
tsConfigPath	string	''	Path to TypeScript configuration file
checkBrowserCompatibility	boolean	false	Enable browser compatibility checking
browserList	string[]	['> 1%', 'last 2 versions', 'not ie <= 11']	Supported browsers list
noIndexImportConfig	object	{}	Configuration for index import rules
noRestrictedImportsConfig	object	undefined	Restricted imports configuration
globals	object	undefined	Additional global variables
additionalPlugins	object	{}	Extra ESLint plugins to include
overrides	array	[]	Configuration overrides

Configuration Examples

Basic TypeScript Project

// eslint.config.js
const eslintConfigKubit = require("eslint-config-kubit");

module.exports = eslintConfigKubit({
  tsConfigPath: "./tsconfig.json",
});

React TypeScript Project

// eslint.config.js
const eslintConfigKubit = require("eslint-config-kubit");

module.exports = eslintConfigKubit({
  isReact: true,
  tsConfigPath: "./tsconfig.json",
  noIndexImportConfig: {
    aliases: {
      "@/components": "./src/components/*",
      "@/utils": "./src/utils/*",
      "@/hooks": "./src/hooks/*",
    },
  },
});

Node.js Project (No React)

// eslint.config.js
const eslintConfigKubit = require("eslint-config-kubit");

module.exports = eslintConfigKubit({
  isReact: false,
  tsConfigPath: "./tsconfig.json",
});

With Browser Compatibility Checks

// eslint.config.js
const eslintConfigKubit = require("eslint-config-kubit");

module.exports = eslintConfigKubit({
  checkBrowserCompatibility: true,
  browserList: [
    "> 0.5%",
    "last 2 versions",
    "Firefox ESR",
    "not dead",
    "iOS >= 10",
    "Safari >= 10",
  ],
  tsConfigPath: "./tsconfig.json",
});

Restricted Imports Configuration

// eslint.config.js
const eslintConfigKubit = require("eslint-config-kubit");

module.exports = eslintConfigKubit({
  noRestrictedImportsConfig: {
    paths: [
      "lodash", // Use lodash-es instead
      "moment", // Use date-fns instead
      {
        name: "react",
        importNames: ["default"],
        message: 'Import React as named import: import { React } from "react"',
      },
    ],
  },
});

�🔧 Customization

Overriding Rules

You can override specific rules for your project needs:

const eslintConfigKubit = require("eslint-config-kubit");

module.exports = eslintConfigKubit({
  overrides: [
    {
      files: ["**/*.{js,jsx,ts,tsx}"],
      rules: {
        // Disable magic number warnings for constants
        "@typescript-eslint/no-magic-numbers": "off",

        // Allow multiple components per file in specific cases
        "react/no-multi-comp": "off",

        // Relax complexity requirements for legacy code
        complexity: ["warn", { max: 10 }],
      },
    },
    {
      files: ["**/*.test.{js,jsx,ts,tsx}", "**/*.spec.{js,jsx,ts,tsx}"],
      rules: {
        // Allow any types in test files
        "@typescript-eslint/no-explicit-any": "off",

        // Allow console.log in tests
        "no-console": "off",
      },
    },
  ],
});

Non-React Projects

For pure TypeScript/JavaScript projects without React:

const eslintConfigKubit = require("eslint-config-kubit");

module.exports = eslintConfigKubit({
  isReact: false,
  tsConfigPath: "./tsconfig.json",
});

🛠️ Development Setup

Usage in Your Project

Add linting scripts to your package.json:

{
  "scripts": {
    "lint": "eslint . --ext .js,.jsx,.ts,.tsx",
    "lint:fix": "eslint . --ext .js,.jsx,.ts,.tsx --fix",
    "lint:cache": "eslint . --ext .js,.jsx,.ts,.tsx --cache"
  }
}

Then run:

# Check for linting errors
pnpm lint

# Automatically fix linting errors
pnpm lint:fix

# Use cache for faster linting
pnpm lint:cache

VS Code Integration

Create .vscode/settings.json for better integration:

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],
  "eslint.experimental.useFlatConfig": true
}

GitHub Actions Workflow

Add ESLint checking to your CI/CD:

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          registry-url: "https://registry.npmjs.org"

      - uses: pnpm/action-setup@v4

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      - uses: actions/cache@v4
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-

      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm type-check

�📋 Included Rules

This configuration includes rules from the following ESLint plugins:

• @typescript-eslint - TypeScript-specific linting rules
• eslint-plugin-react - React specific linting rules
• eslint-plugin-react-hooks - Rules of Hooks
• eslint-plugin-jsx-a11y - Accessibility rules
• eslint-plugin-import - Import/export syntax rules
• eslint-plugin-prettier - Prettier integration
• eslint-plugin-jest - Jest testing rules
• eslint-plugin-perfectionist - Sorting and organization rules

Migration Guide

From v0.x to v1.0.0

Version 1.0.0 introduces several breaking changes:

ESLint Flat Config

• Required: ESLint 9.x with flat config format
• Change: Update your eslint.config.js file format

Before (v0.x):

module.exports = {
  extends: ["eslint-config-kubit"],
};

After (v1.0.0):

const eslintConfigKubit = require("eslint-config-kubit");

module.exports = eslintConfigKubit();

Dependency Updates

• Node.js: Minimum version is now 18.0.0
• TypeScript: Support for TypeScript 5.x
• React: Support for React 18+

Configuration Changes

• Parameter structure has been simplified
• Better default values for all options
• Improved TypeScript integration

🤝 Contributing

We welcome contributions! This project uses pnpm for package management and follows a fork-based contribution workflow.

Quick Contribution Guide

1. Fork the repository
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/eslint-config-kubit.git
3. Install dependencies: pnpm install
4. Create a branch: git checkout -b feat/amazing-feature
5. Make your changes to the ESLint configuration
6. Test thoroughly with sample projects
7. Commit: git commit -m 'feat(rules): add amazing feature'
8. Push: git push origin feat/amazing-feature
9. Open a Pull Request from your fork

Note: This project uses Changesets for automatic version management. Just use proper branch naming (feat/, fix/, break/) and the rest is handled automatically!

For detailed guidelines, see our Contributing Guide.

Development Commands

# Install dependencies
pnpm install

# Add a changeset (optional - auto-generated if not provided)
pnpm changeset

# Link for local testing
pnpm link --global

# Test in another project
cd /path/to/test-project
pnpm link --global eslint-config-kubit

Release Process (Fully Automatic)

This project uses Changesets for automated releases:

1. Create PR with proper branch naming (feat/, fix/, break/)
2. PR gets merged to main
3. Automatically:
   • Version is bumped based on branch name
   • CHANGELOG is updated
   • Package is published to NPM
   • GitHub Release is created
   • PR is commented with publish details

📚 Documentation

• Full Documentation
• Contributing Guide
• Code of Conduct
• Security Policy
• Changelog

📖 Related Packages

• @kubit-ui-web/react-components - Kubit React component library
• @kubit-ui-web/design-system - Kubit design system
• eslint - The core ESLint linting library
• typescript - TypeScript compiler
• prettier - Code formatter

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

❓ Troubleshooting

Common Issues

"Cannot find module 'eslint-config-kubit'"

Make sure you've installed the package:

npm install --save-dev eslint-config-kubit

"Parsing error" with TypeScript files

Ensure you've set the correct tsConfigPath:

module.exports = eslintConfigKubit({
  tsConfigPath: "./tsconfig.json", // Path relative to your project root
});

Rules are too strict

You can override specific rules:

module.exports = eslintConfigKubit({
  overrides: [
    {
      files: ["**/*.{js,jsx,ts,tsx}"],
      rules: {
        complexity: ["warn", { max: 10 }], // Increase complexity limit
        "@typescript-eslint/no-magic-numbers": "off", // Disable magic numbers
      },
    },
  ],
});

Performance Tips

• Use .eslintignore: Exclude node_modules, dist, and other build folders
• Limit file patterns: Only lint files you need to check
• Use caching: Add --cache flag to ESLint commands

🎯 Roadmap

• ESLint 10.x compatibility when released
• Additional framework support (Vue, Svelte)
• Custom rule presets for different project types
• Performance optimizations for large codebases
• Enhanced TypeScript 5.x support
• Improved monorepo configurations

🤝 Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions
• ⭐ Give us a star if this project helped you!

📈 Stats

---

Made with ❤️ by the Kubit Team

If this project helped you, please consider giving it a ⭐ on GitHub!