Overview

JS Style Kit provides a comprehensive ESLint configuration using the modern ESLint v9 flat config format. This configuration includes sensible defaults for JavaScript and TypeScript projects, with optional support for React, testing frameworks, and code organization.

Basic Setup

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

import { eslintConfig } from "js-style-kit";

export default eslintConfig();

If your project doesn’t use ESM, create an eslint.config.mjs file instead:

import { eslintConfig } from "js-style-kit";

export default eslintConfig();

Add the linting scripts to your package.json:

{
  "scripts": {
    "lint": "eslint . --max-warnings 0",
    "lint:fix": "eslint . --fix --max-warnings 0"
  }
}

Configuration Options

The eslintConfig() function accepts a configuration object with the following options:

import { eslintConfig } from "js-style-kit";

export default eslintConfig({
  // All options shown with their default values
  functionStyle: "arrow", // Controls function style: "arrow", "declaration", "expression", or "off"
  ignores: [], // Additional paths to ignore (node_modules and dist already excluded)
  importPlugin: true, // Whether to include import plugin rules
  jsdoc: { requireJsdoc: false }, // JSDoc configuration or false to disable
  react: false, // Whether to include React rules, see below for options
  rules: {}, // Custom rules to override or configure specific ESLint rules
  sorting: true, // Whether to include sorting rules from Perfectionist
  storybook: false, // Whether to include Storybook rules
  testing: true, // Testing configuration, see below for options
  typescript: true, // Boolean or string path to tsconfig.json
  turbo: false, // Whether to include Turborepo rules
  unicorn: true, // Whether to include Unicorn rules
});

Function Style Configuration

Controls how functions should be written throughout your codebase. Some configurations are auto-fixable, but some may require manual adjustment.

// Enforce arrow functions (default)
functionStyle: "arrow";

// Enforce function declarations
functionStyle: "declaration";

// Enforce function expressions
functionStyle: "expression";

// Disable function style enforcement
functionStyle: "off";

TypeScript Configuration

TypeScript support is enabled by default. You can:

// Enable with automatic project detection (default)
typescript: true;

// Disable TypeScript rules
typescript: false;

// Specify path to your tsconfig.json
typescript: "./tsconfig.json";

Import Plugin Configuration

The import plugin rules are enabled by default. These rules help maintain proper import/export syntax and detect issues with imports.

// Enable import plugin (default)
importPlugin: true;

// Disable import plugin
importPlugin: false;

Custom Rules Configuration

You can override or configure specific ESLint rules using the rules option:

// Add custom rule configurations
rules: {
  // Format is the same as standard ESLint rule configuration
  "no-console": ["error", { allow: ["warn", "error"] }],
  "@typescript-eslint/no-explicit-any": "off",
  // Any valid ESLint rule can be configured here
}

React Configuration

React support is disabled by default.

// Enable React support with default options (includes React Compiler)
react: true;

// Disable React support
react: false;

// Enable with custom options
react: {
  // Enable/disable React Compiler (default: true when react is enabled)
  reactCompiler: true,

  // Controls React Fast Refresh validation
  reactRefresh: false,

  // Controls framework-specific configurations: "next", "vite", or "none"
  framework: "next"
}

JSDoc Configuration

JSDoc validation is enabled by default, but requirement rules are off:

// Disable JSDoc validation completely
jsdoc: false;

// Enable JSDoc with requirement rules, ideal for libraries
jsdoc: {
  requireJsdoc: true;
}

Sorting Configuration

Code organization rules from Perfectionist are enabled by default:

// Enable sorting rules (default)
sorting: true;

// Disable sorting rules
sorting: false;

Testing Configuration

Testing support is enabled by default with Vitest configuration. You can customize it or disable it entirely:

// Enable with default settings (Vitest)
testing: true;

// Disable testing configuration
testing: false;

// Enable with custom options
testing: {
  filenamePattern: "spec", // "test" (.test, default) or "spec" (.spec)
  files: ["**/*.{test,spec}.{ts,tsx,js,jsx}"], // Override file patterns
  formattingRules: true, // Whether to include formatting rules like padding around blocks
  framework: "vitest", // "vitest" (default), "jest", "node", or "bun"
  itOrTest: "test", // "it" (default) or "test"
}

Storybook Configuration

Storybook support is disabled by default.

// Enable Storybook support with default options
storybook: true;

// Disable Storybook support
storybook: false;

Additional Rules

// Enable Turborepo rules (disabled by default)
turbo: true;

// Enable Unicorn rules (enabled by default)
unicorn: true;

Adding Ignores

By default, JS Style Kit ignores node_modules and dist directories. You can add additional paths to ignore:

export default eslintConfig({
  ignores: ["build", ".cache", "coverage"],
});

Custom ESLint Configurations

You can extend the base configuration by providing additional ESLint config objects as rest parameters:

import { eslintConfig } from "js-style-kit";

export default eslintConfig(
  {
    // Base configuration options
    typescript: "tsconfig.eslint.json",
    react: true,
    // Use the built-in rules parameter for custom rules
    rules: {
      "no-console": ["error", { allow: ["warn", "error"] }],
      "prefer-const": "error",
    },
    // Configure testing
    testing: {
      framework: "jest",
      itOrTest: "test",
    },
  },
  // You can still add additional config objects
  {
    name: "custom-globals",
    languageOptions: {
      globals: {
        process: "readonly",
        __dirname: "readonly",
      },
    },
  },
);

Migrating from ESLint Legacy Config

If you’re coming from a legacy ESLint configuration (.eslintrc.js or other formats), you’ll need to adapt to the new flat config format. Here are some key differences:

  1. The configuration file is now named eslint.config.js or eslint.config.mjs
  2. The format is different, using an array of configuration objects rather than a nested object
  3. Plugins, parsers, and other extensions are imported directly rather than being referenced by string names

JS Style Kit handles most of this complexity for you, so you can focus on the configuration options that matter for your project.

For more details on ESLint flat config, see the ESLint documentation.