ESLint-Config 🛡️

A comprehensive and modular ESLint configuration system by ElsiKora

📚 Table of Contents

• Description
• Features
• Installation
• Usage
• Roadmap
• FAQ
• License

📖 Description

ESLint-Config provides a sophisticated, modular ESLint configuration system that simplifies the enforcement of consistent code style and quality standards across projects. It offers a range of specialized rule sets for various environments, frameworks, and languages including TypeScript, React, Next.js, NestJS, and more. By adopting this package, development teams can ensure code consistency, reduce bugs, improve maintainability, and accelerate onboarding processes for new team members. The plugin-based architecture makes it easy to adapt to different project requirements while maintaining a consistent coding style across your organization.

🚀 Features

• ✨ ✅ Highly modular and customizable configuration system with granular control
• ✨ ✅ Comprehensive TypeScript support with strict type checking and naming conventions
• ✨ ✅ First-class React, Next.js and NestJS integration with specialized rules
• ✨ ✅ Built-in support for modern CSS, Tailwind, JSON, YAML and Markdown linting
• ✨ ✅ Format-agnostic with Prettier compatibility for consistent code style
• ✨ ✅ Advanced code quality rules from SonarJS and perfectionists
• ✨ ✅ Robust file structure enforcement with check-file plugin
• ✨ ✅ Smart plugin name remapping to avoid conflicts
• ✨ ✅ Optimized for monorepos and multi-framework projects
• ✨ ✅ Extensive test coverage and E2E validation

🛠 Installation

# Using npm
npm install --save-dev @elsikora/eslint-config

# Using yarn
yarn add --dev @elsikora/eslint-config

# Using pnpm
pnpm add --save-dev @elsikora/eslint-config

# Using bun
bun add --dev @elsikora/eslint-config


Optional dependencies will be installed based on your configuration requirements. For example, if you plan to use TypeScript linting, ensure you have the TypeScript-related ESLint plugins installed.

💡 Usage

Basic Usage

Create an eslint.config.js file at the root of your project:

import { createConfig } from "@elsikora/eslint-config";

export default createConfig({
    withTypescript: true,
    withPrettier: true
});

With Ignore Patterns

import { createConfig } from "@elsikora/eslint-config";

const config = {
    ignores: [
        "node_modules/**",
        "dist/**",
        "build/**",
        "coverage/**"
    ]
};

export default [
    config,
    ...(await createConfig({
        withTypescript: true,
        withJavascript: true,
        withPrettier: true
    }))
];

TypeScript Project Configuration

For a TypeScript project with React:

import { createConfig } from "@elsikora/eslint-config";

export default createConfig({
    withTypescript: true,
    withReact: true,
    withStylistic: true,
    withSonar: true
});

NestJS Backend Configuration

import { createConfig } from "@elsikora/eslint-config";

export default createConfig({
    withTypescript: true,
    withNest: true,
    withTypeorm: true,
    withNode: true
});

Next.js Full-Stack Configuration

import { createConfig } from "@elsikora/eslint-config";

export default createConfig({
    withTypescript: true,
    withReact: true,
    withNext: true,
    withTailwindCss: true,
    withNode: true,
    withPrettier: true
});

Available Configuration Options

The configuration factory accepts the following options:

interface IConfigOptions {
    withCheckFile?: boolean;      // File structure and naming convention rules
    withCss?: boolean;           // CSS linting
    withJavascript?: boolean;    // JavaScript rules
    withJsDoc?: boolean;         // JSDoc validation
    withJson?: boolean;          // JSON linting
    withJsx?: boolean;           // JSX a11y rules
    withMarkdown?: boolean;      // Markdown linting
    withNest?: boolean;          // NestJS specific rules
    withNext?: boolean;          // Next.js specific rules
    withNode?: boolean;          // Node.js specific rules
    withPackageJson?: boolean;   // package.json validation
    withPerfectionist?: boolean; // Sorting imports, props, etc.
    withPrettier?: boolean;      // Prettier integration
    withReact?: boolean;         // React rules
    withRegexp?: boolean;        // RegExp validation
    withSonar?: boolean;         // SonarJS code quality rules
    withStylistic?: boolean;     // Code style rules
    withTailwindCss?: boolean;   // Tailwind CSS specific rules
    withTypeorm?: boolean;       // TypeORM specific rules
    withTypescript?: boolean;    // TypeScript rules
    withUnicorn?: boolean;       // Unicorn rules
    withYaml?: boolean;          // YAML linting
}

CLI Usage

Run ESLint using your configured rules:

# Check files
npx eslint "src/**/*.{ts,tsx,js,jsx}"

# Fix issues automatically
npx eslint "src/**/*.{ts,tsx,js,jsx}" --fix

Package.json Integration with lint-staged

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ]
  }
}

VS Code Integration

Create a .vscode/settings.json file:

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "eslint.validate": [
    "javascript",
    "typescript",
    "javascriptreact",
    "typescriptreact",
    "json",
    "jsonc",
    "yaml"
  ]
}

Advanced: Custom Rule Extension

You can extend the configuration with your own custom rules:

import { createConfig } from "@elsikora/eslint-config";

export default [
    ...(await createConfig({
        withTypescript: true,
        withReact: true
    })),
    {
        rules: {
            // Override or add custom rules
            "@elsikora-typescript/naming-convention": ["error", {
                // Your custom configuration
            }]
        }
    }
];

🛣 Roadmap

❓ FAQ

Frequently Asked Questions

How do I migrate from a traditional .eslintrc configuration?

ESLint 9.x and above use the new flat config format. To migrate, convert your existing .eslintrc file to an eslint.config.js file and use the createConfig function with the appropriate options to match your previous setup.

Will this work with my editor's ESLint plugin?

Yes, modern editor ESLint plugins (VS Code, WebStorm, etc.) support the new flat config format used by this package.

How does this handle conflicting rules between plugins?

The configuration has been carefully designed to avoid rule conflicts. When conflicts might occur, we've established a priority system, generally favoring TypeScript-specific rules over general ESLint rules when applicable.

Can I use this with Prettier?

Yes! Enable the withPrettier option to integrate Prettier. This will ensure ESLint doesn't conflict with Prettier's formatting rules.

Does this support React Native projects?

Yes, you can use this with React Native by enabling the withReact option. Additional React Native specific rules may need to be added separately.

How do I debug rule conflicts or issues?

You can run ESLint with the --debug flag to see detailed information about rule resolution and conflicts:

npx eslint --debug src/file.ts

How can I contribute to this project?

Contributions are welcome! Please check the contribution guidelines in the repository for information on how to submit issues or pull requests.

🔒 License

This project is licensed under **MIT License

Copyright (c) 2025 ElsiKora

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.**.

📋 Changelog

See CHANGELOG.md for details.