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:
- The configuration file is now named
eslint.config.js
or eslint.config.mjs
- The format is different, using an array of configuration objects rather than a nested object
- 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.