@lightbase/eslint-config

ESLint config

Opinionated but configurable ESLint config. Fully includes linting and formatting.

Install

npm install --save-dev --exact @lightbase/eslint-config

Some configurations require manually installed plugins. For example

npm install --save-dev --exact eslint-plugin-react eslint-plugin-react-hooks

This is documented below.

Usage

This package builds a config, compatible with ESLint Flat Config. To use the config, create the following eslint.config.js file:

import { defineConfig } from "@lightbase/eslint-config";

export default defineConfig({});

Commands

Add the following scripts to your package.json:

{
	"scripts": {
		"lint": "eslint . --concurrency=auto --fix --cache --cache-location .cache/eslint/",
		"lint:ci": "eslint . --concurrency=auto"
	}
}

Make sure to add .cache to your .gitignore

[!NOTE]

In a CommonJS project, make sure to name your file eslint.config.mjs instead.

Default configuration and options

Prettier

Prettier is configured to run on all Markdown, JSON, YAML, JavaScript and TypeScript files. We support the following configuration to override this:

import { defineConfig } from "@lightbase/eslint-config";

export default defineConfig({
	prettier: {
		globalOverride: {
			// Override Prettier options for all supported files.
		},
		languageOverrides: {
			ts: {
				// Override Prettier options for a specific file
				// group.
			},
		},
	},
});

Prettier can be disabled entirely by passing false:

import { defineConfig } from "@lightbase/eslint-config";

export default defineConfig({
	prettier: false,
});

Using an external formatter (e.g. Oxfmt)

If you use an external formatter like Oxfmt instead of Prettier, you should disable Prettier and import ordering rules to avoid conflicts:

import { defineConfig } from "@lightbase/eslint-config";

export default defineConfig({
	prettier: false,
	disableImportOrdering: true,
});

This disables:

• All Prettier formatting rules
• import-x/order, import-x/first, and import-x/newline-after-import
• Custom React import grouping (if react is enabled)

All other rules (TypeScript, JSDoc, comment-length, React logic, accessibility, etc.) are purely semantic and do not conflict with external formatters.

Typescript

Typescript ESLint is automatically enabled if a tsconfig.json is present.

import { defineConfig } from "@lightbase/eslint-config";

export default defineConfig(
	{},
	{
		// Apply custom rules
		files: ["**/*.ts"],
		rules: {
			"@typescript-eslint/no-unused-vars": "off",
		},
	},
);

Or explicitly disabling Typescript support can be done with:

import { defineConfig } from "@lightbase/eslint-config";

export default defineConfig({
	typescript: false,
});

By default, we enable the recommended type checked rules from typescript-eslint. To disable these rules, use:

import { defineConfig } from "@lightbase/eslint-config";

export default defineConfig({
	typescript: {
		disableTypeCheckedRules: true,
	},
});

Markdown

A Markdown processor is installed by default. Its purpose is to extract code-blocks and present them as virtual files. This means that markdown code-blocks can receive custom rules as follows:

import { defineConfig } from "@lightbase/eslint-config";

export default defineConfig(
	{},
	{
		files: ["**/*.md/*.js"],
		rules: {
			"no-unused-vars": "off",
		},
	},
);

React

The config optionally supports enabling React and Next.js specific rules. Add the following dependencies:

npm install --save-dev --exact eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y eslint-plugin-no-relative-import-paths

If you use Next.js, make sure to also add @next/eslint-plugin-next via:

npm install --save-dev --exact @next/eslint-plugin-next

React is only support in combination with Typescript (see above), and can be enabled as follows:

import { defineConfig } from "@lightbase/eslint-config";

export default defineConfig({
	react: {
		withNextJs: true,
	},
});

This enables all Next.js rules and various recommended rules for React, hooks usage, and JSX accessibility.

Globals

The config by default includes all globals for Node.js, Browser, and ES2021. You can use other predefined presets via

import { defineConfig } from "@lightbase/eslint-config";

export default defineConfig({
	// Make sure to include the full setup.
	globals: ["browser", "serviceworker"],
});

This enables environment-specific globals for all files. For a stricter setup, use custom configuration as explained below

import globals from "globals";
import { defineConfig } from "@lightbase/eslint-config";

export default defineConfig(
	{},
	{
		files: ["**/*.js"],
		languageOptions: {
			globals: {
				...globals.es2015,
			},
		},
	},
);

Ignores

ESLint will by default ignore everything as defined in your .gitignore. You can add new directories like so.

import { defineConfig } from "@lightbase/eslint-config";

export default defineConfig(
	{
		// Define config options, explained above.
	},
	{
		// Ignore the packages/ directory.
		ignores: ["packages/**"],
	},
);

Make sure that nested directory ignores contain the proper wildcards for them to work.

# works
.cache
**/src/generated

# doesn't work
src/generated

Custom configuration

defineConfig accepts custom ESLint configuration as the 'rest' parameter. This allows you to configure rules for specific file patterns.

import { defineConfig } from "@lightbase/eslint-config";

export default defineConfig(
	{
		// Define config options, explained above.
	},
	{
		// Ignore the packages/ directory.
		ignores: ["packages/**"],
	},
	{
		// Add rules for specific files.
		file: ["**/*.ts"],
		rules: {
			"no-console": "off",
		},
	},
);

IDE

WebStorm

Configuring Webstorm to use this config can be done as follows:

• Go to Languages & Frameworks -> JavaScript -> Code Quality Tools -> ESLint
• Select Automatic ESLint configuration
• Set Run for files to **/*.*
• Select Run eslint --fix on save
• Click on Apply & OK

Since this config is configured to automatically cleanup imports, and runs Prettier as part of ESLint, you can disable these settings in the Actions on Save-settings of WebStorm.

[!NOTE]

WebStorm sometimes doesn't pick up on an updated ESLint configuration. A restart of the background services fixes this.

• In versions 2023.3 and below, go to the ESLint settings in your preferences according to the steps above. Select Disable ESLint configuration, click on Apply and select Automatic ESLint configuration again.
• In versions 20241.1 and above use Help -> Find action -> Restart ESLint Service.

Credits

Inspired by Dirkdev98's initial design, solidified with @antfu/eslint-config.

License

MIT