super-configs

super-configs

Shared ESLint, Biome, Bun, Commitlint, Jest, Vitest, Markdownlint, Stylelint, TypeDoc, and legacy Prettier configurations for JavaScript, TypeScript, React, CSS, and Markdown projects.

Installation

npm install super-configs --save-dev
# or
pnpm add super-configs -D
# or
yarn add super-configs -D
# or
bun add super-configs -D

Peer Dependencies

This package requires the following peer dependencies:

npm install eslint@^10 typescript@^6 --save-dev

ESLint 10 requires Node.js 20.19+, 22.13+, or 24+; odd-numbered Node.js releases are not supported.

The Node.js TypeScript preset also requires Node.js declarations:

npm install @types/node --save-dev

TypeScript 6 consumers can keep using the standard typescript package. To compile with TypeScript 7 while keeping TypeScript 6 available to tools such as typescript-eslint, TypeDoc, and ts-jest, install both versions with aliases:

npm install \
  typescript@npm:@typescript/typescript6@^6.0.2 \
  @typescript/native@npm:typescript@^7.0.2 \
  --save-dev

With this setup, tsc runs TypeScript 7 and tsc6 runs TypeScript 6. Consumers are not required to migrate to TypeScript 7.

Biome, Commitlint, Jest, Vitest, Markdownlint, Stylelint, TypeDoc, and Prettier are optional peers. Use Biome for new projects:

npm install @biomejs/biome --save-dev

Use Markdownlint for Markdown projects:

npm install markdownlint --save-dev

Use Commitlint for Conventional Commits:

npm install @commitlint/cli @commitlint/config-conventional --save-dev

Use Jest for TypeScript test projects:

npm install jest ts-jest --save-dev

Use Vitest for TypeScript test projects:

npm install vitest --save-dev

Use Stylelint for CSS projects:

npm install stylelint stylelint-config-standard --save-dev

Use TypeDoc for TypeScript API documentation:

npm install typedoc --save-dev

Usage

Root Export

Prefer subpath imports for config files. The root export is available when you want to import multiple JavaScript configs from one place:

import { eslintTs, prettierConfig } from 'super-configs';

export { eslintTs, prettierConfig };

TypeScript

Extend the shared preset that matches your project. Define project-specific paths such as rootDir, outDir, and include in your own tsconfig.json.

Node.js

{
  "extends": "super-configs/tsconfig/node",
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src/**/*.ts"]
}

React

{
  "extends": "super-configs/tsconfig/react",
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src/**/*.ts", "src/**/*.tsx"]
}

Recommended Project Setup

Install the shared config and the peer tools used by your project:

npm install super-configs eslint@^10 typescript@^6 @types/node @biomejs/biome --save-dev

Add scripts to your package.json:

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "format": "biome check --write .",
    "format:check": "biome check .",
    "check": "npm run lint && npm run format:check"
  }
}

CLI

Run the init command from a local install:

npx super-configs init --runtime bun --language ts --type-checked

If installed globally, use the binary directly:

super-configs init --runtime node --language ts

The command creates starter config files and skips existing files unless --force is passed.

Add companion presets and package scripts when needed:

super-configs init --runtime bun --language ts --type-checked --vitest --scripts
super-configs init --react --vitest

ESLint

Config factory

Use the factory when you want one import and a runtime switch. Defaults are Node.js and TypeScript.

// eslint.config.js
import { createEslintConfig } from 'super-configs/eslint';

export default createEslintConfig({
  runtime: 'bun',
  language: 'ts',
  typeChecked: true,
  ignores: ['dist/**', 'coverage/**'],
});

JavaScript

// eslint.config.js
import eslintJs from 'super-configs/eslint/js';

export default [
  ...eslintJs,
];

TypeScript

// eslint.config.js
import eslintTs from 'super-configs/eslint/ts';

export default [
  ...eslintTs,
];

Runtime presets

Choose an explicit runtime when code does not run in Node.js. The existing eslint/js and eslint/ts imports remain Node.js defaults for backwards compatibility.

Runtime	JavaScript	TypeScript	Type-checked TypeScript
Node.js	super-configs/eslint/node/js	super-configs/eslint/node/ts	super-configs/eslint/node/ts-type-checked
Browser	super-configs/eslint/browser/js	super-configs/eslint/browser/ts	super-configs/eslint/browser/ts-type-checked
Bun	super-configs/eslint/bun/js	super-configs/eslint/bun/ts	super-configs/eslint/bun/ts-type-checked

// eslint.config.js
import eslintBrowserTs from 'super-configs/eslint/browser/ts';

export default [
  ...eslintBrowserTs,
];

Type-aware TypeScript

Type-aware presets enable typescript-eslint recommended type-checked rules with parserOptions.projectService. Each linted TypeScript file must belong to its nearest tsconfig.json. Typed linting is slower but catches unsafe assignments, floating promises, and other issues requiring TypeScript type information.

// eslint.config.js
import eslintTsTypeChecked from 'super-configs/eslint/ts-type-checked';

export default [
  ...eslintTsTypeChecked,
];

The short eslint/ts-type-checked import uses Node.js globals. Choose a runtime-specific import from the table above for Browser or Bun projects.

Jest

Use this alongside the JavaScript, TypeScript, or React presets when your project has Jest tests.

// eslint.config.js
import eslintTs from 'super-configs/eslint/ts';
import eslintJest from 'super-configs/eslint/jest';

export default [
  ...eslintTs,
  ...eslintJest,
];

Vitest

Use this alongside the JavaScript, TypeScript, or React presets when your project has Vitest tests.

// eslint.config.js
import eslintTs from 'super-configs/eslint/ts';
import eslintVitest from 'super-configs/eslint/vitest';

export default [
  ...eslintTs,
  ...eslintVitest,
];

Common TypeScript library setup:

// eslint.config.js
import eslintTs from 'super-configs/eslint/ts';

export default [
  {
    ignores: ['dist/**', 'coverage/**', 'node_modules/**'],
  },
  ...eslintTs,
];

React JSX

// eslint.config.js
import eslintReactJsx from 'super-configs/eslint/react/jsx';

export default [
  ...eslintReactJsx,
];

React TSX

// eslint.config.js
import eslintReactTsx from 'super-configs/eslint/react/tsx';

export default [
  ...eslintReactTsx,
];

Common React + TypeScript setup:

// eslint.config.js
import eslintReactTsx from 'super-configs/eslint/react/tsx';

export default [
  {
    ignores: ['dist/**', 'coverage/**', 'storybook-static/**', 'node_modules/**'],
  },
  ...eslintReactTsx,
];

Biome

{
  "$schema": "https://biomejs.dev/schemas/2.4.16/schema.json",
  "extends": ["super-configs/biome"]
}

If your Biome version cannot resolve package exports, use the direct path:

{
  "$schema": "https://biomejs.dev/schemas/2.4.16/schema.json",
  "extends": ["./node_modules/super-configs/biome.json"]
}

Commitlint

Use the shared Commitlint config:

// commitlint.config.js
import commitlintConfig from 'super-configs/commitlint';

export default commitlintConfig;

Add a commit message check script:

{
  "scripts": {
    "commitlint": "commitlint --from HEAD~1 --to HEAD --verbose"
  }
}

Markdownlint

Point Markdownlint-compatible tools at the shared JSON config:

import { lint, readConfig } from 'markdownlint/sync';

const config = readConfig('./node_modules/super-configs/markdownlint.json');
const results = lint({ files: ['README.md'], config });

console.dir(results, { colors: true, depth: null });

Or add a .markdownlint.json file for editors and CLI wrappers:

{
  "extends": "./node_modules/super-configs/markdownlint.json"
}

EditorConfig

Copy the shared template into a project root:

cp node_modules/super-configs/.editorconfig .editorconfig

Jest

Use the shared Jest config:

// jest.config.js
import jestConfig from 'super-configs/jest';

export default jestConfig;

Or extend it:

// jest.config.js
import jestConfig from 'super-configs/jest';

export default {
  ...jestConfig,
  testMatch: ['**/*.test.ts'],
};

Vitest

Use the shared Vitest config:

// vitest.config.ts
import vitestConfig from 'super-configs/vitest';

export default vitestConfig;

Or extend it:

// vitest.config.ts
import { mergeConfig } from 'vitest/config';
import vitestConfig from 'super-configs/vitest';

export default mergeConfig(vitestConfig, {
  test: {
    include: ['src/**/*.test.ts'],
  },
});

Bun test

Bun does not support extending a package bunfig.toml. Copy the shared template into your project root so relative coverage paths resolve inside your project:

cp node_modules/super-configs/lib/test/bunfig.toml bunfig.toml

The template enables text and LCOV coverage, writes reports to coverage, skips test files from coverage, and ignores common generated directories. Run it with:

bun test

The same template is exposed through the super-configs/bunfig and super-configs/bunfig.toml package subpaths for tooling that resolves package exports.

Stylelint

Use the shared Stylelint config:

// stylelint.config.js
import stylelintConfig from 'super-configs/stylelint';

export default stylelintConfig;

Or extend it:

// stylelint.config.js
import stylelintConfig from 'super-configs/stylelint';

export default {
  ...stylelintConfig,
  rules: {
    ...stylelintConfig.rules,
    'selector-class-pattern': '^[a-z][a-zA-Z0-9]+
TypeDoc
Extend the shared TypeDoc config:
{
  "$schema": "https://typedoc.org/schema.json",
  "extends": "./node_modules/super-configs/typedoc.json",
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "readme": "README.md",
  "exclude": ["**/*.test.ts", "**/*.spec.ts", "**/test/**"]
}
Add a docs script:
{
  "scripts": {
    "docs": "typedoc --options typedoc.json"
  }
}
Prettier
Prefer Biome for new projects. The Prettier export remains available for existing projects that still consume it.
// prettier.config.js
import prettierConfig from 'super-configs/prettier';

export default prettierConfig;
Or extend the configuration:
// prettier.config.js
import prettierConfig from 'super-configs/prettier';

export default {
  ...prettierConfig,
  // your overrides here
  printWidth: 120,
};
Recipes
Node.js Library
// eslint.config.js
import { createEslintConfig } from 'super-configs/eslint';
import eslintVitest from 'super-configs/eslint/vitest';

export default [
  ...createEslintConfig({
    runtime: 'node',
    language: 'ts',
    typeChecked: true,
    ignores: ['dist/**', 'coverage/**'],
  }),
  ...eslintVitest,
];
{
  "extends": "super-configs/tsconfig/node",
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src/**/*.ts"]
}
Browser App
// eslint.config.js
import { createEslintConfig } from 'super-configs/eslint';

export default createEslintConfig({
  runtime: 'browser',
  language: 'ts',
  ignores: ['dist/**', 'coverage/**'],
});
Bun Service
// eslint.config.js
import { createEslintConfig } from 'super-configs/eslint';

export default createEslintConfig({
  runtime: 'bun',
  language: 'ts',
  typeChecked: true,
  ignores: ['dist/**', 'coverage/**'],
});
cp node_modules/super-configs/lib/test/bunfig.toml bunfig.toml
React App
// eslint.config.js
import eslintReactTsx from 'super-configs/eslint/react/tsx';
import eslintVitest from 'super-configs/eslint/vitest';

export default [
  {
    ignores: ['dist/**', 'coverage/**', 'storybook-static/**'],
  },
  ...eslintReactTsx,
  ...eslintVitest,
];
{
  "extends": "super-configs/tsconfig/react",
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src/**/*.ts", "src/**/*.tsx"]
}
Available Configurations



Export
Description



super-configs/eslint
ESLint config factory for Node.js, Browser, and Bun projects


super-configs/eslint/js
ESLint configuration for JavaScript


super-configs/eslint/ts
ESLint configuration for TypeScript


super-configs/eslint/ts-type-checked
Type-aware ESLint configuration for TypeScript


super-configs/eslint/node/js
ESLint configuration for Node.js JavaScript


super-configs/eslint/node/ts
ESLint configuration for Node.js TypeScript


super-configs/eslint/node/ts-type-checked
Type-aware ESLint configuration for Node.js TypeScript


super-configs/eslint/browser/js
ESLint configuration for Browser JavaScript


super-configs/eslint/browser/ts
ESLint configuration for Browser TypeScript


super-configs/eslint/browser/ts-type-checked
Type-aware ESLint configuration for Browser TypeScript


super-configs/eslint/bun/js
ESLint configuration for Bun JavaScript


super-configs/eslint/bun/ts
ESLint configuration for Bun TypeScript


super-configs/eslint/bun/ts-type-checked
Type-aware ESLint configuration for Bun TypeScript


super-configs/eslint/jest
ESLint overrides for Jest test files


super-configs/eslint/vitest
ESLint overrides for Vitest test files


super-configs/eslint/react/jsx
ESLint configuration for React with JSX


super-configs/eslint/react/tsx
ESLint configuration for React with TSX


super-configs/biome
Biome configuration for formatting, linting, and import organization


super-configs/bunfig
Bun test configuration template with coverage enabled


super-configs/commitlint
Commitlint configuration for Conventional Commits


node_modules/super-configs/.editorconfig
EditorConfig template for common project files


super-configs/jest
Jest configuration for TypeScript test projects


super-configs/vitest
Vitest configuration for TypeScript test projects


super-configs/markdownlint
Markdownlint configuration for Markdown docs


super-configs/stylelint
Stylelint configuration for CSS projects


super-configs/typedoc
TypeDoc configuration for TypeScript API docs


super-configs/prettier
Prettier configuration


Included Rules
Code Quality

Curly braces - Requires curly braces for all control statements (curly)
Strict equality - Requires === and !== (eqeqeq)
Unused variables - Warns on unused variables, ignoring args prefixed with _
Destructuring - Prefer destructuring object properties and array items before using them
Environment variables - Prefer destructuring process.env over bracket notation
Async flow - Requires async/await instead of .then() and .catch()

Examples:
// Invalid
if (isReady) start();

// Valid
if (isReady) {
  start();
}
// Invalid
if (count == '1') {
  start();
}

// Valid
if (count === 1) {
  start();
}
// Warns: `event` is unused
function handleClick(event) {
  save();
}

// Valid: ignored args can start with `_`
function handleClick(_event) {
  save();
}
// Invalid
const userName = user.name;
const firstUser = users[0];
const input = { name: user['name'] as string };
function getName(name = user['name']) {
  return name;
}

// Valid
const { name } = user;
const [firstUser] = users;
const userName = name;
const input = { name };
function getName(name = user.name) {
  return name;
}
// Invalid
const NODE_ENV = process.env['NODE_ENV'];

// Valid
const { NODE_ENV } = process.env;
// Invalid
fetchUser()
  .then((user) => saveUser(user))
  .catch((error) => reportError(error));

// Valid
try {
  const user = await fetchUser();
  await saveUser(user);
} catch (error) {
  reportError(error);
}
Formatting and import organization are handled by Biome, not ESLint.
ESLint Plugins

@eslint/js - ESLint recommended rules
typescript-eslint - TypeScript support
eslint-plugin-react - React rules
eslint-plugin-react-hooks - React Hooks rules
eslint-plugin-jsx-a11y - JSX accessibility

Biome Configuration

Semicolons enabled
Single quotes
Double quotes in JSX attributes
Print width: 100 characters
Tab width: 2 spaces
Trailing commas: all
Arrow parens: always
Import organization enabled
Block statements required for control flow (useBlockStatements)

Examples:
// Invalid
while (isRunning) tick();

// Valid
while (isRunning) {
  tick();
}
// Invalid
const label = "ready"
const items = [one, two]

// Formatted
const label = 'ready';
const items = [one, two];
Development
# Install dependencies
npm install

# Build the project
npm run build

# Lint
npm run lint

# Format code
npm run format

# Run all checks
npm run check
Changelog
See CHANGELOG.md for details.
License
MIT  Ivan
,
  },
};

TypeDoc

Extend the shared TypeDoc config:

__CODE_BLOCK_45__

Add a docs script:

__CODE_BLOCK_46__

Prettier

Prefer Biome for new projects. The Prettier export remains available for existing projects that still consume it.

__CODE_BLOCK_47__

Or extend the configuration:

__CODE_BLOCK_48__

Recipes

Node.js Library

__CODE_BLOCK_49__ __CODE_BLOCK_50__

Browser App

__CODE_BLOCK_51__

Bun Service

__CODE_BLOCK_52__ __CODE_BLOCK_53__

React App

__CODE_BLOCK_54__ __CODE_BLOCK_55__

Available Configurations

Export	Description
__INLINE_CODE_29__	ESLint config factory for Node.js, Browser, and Bun projects
__INLINE_CODE_30__	ESLint configuration for JavaScript
__INLINE_CODE_31__	ESLint configuration for TypeScript
__INLINE_CODE_32__	Type-aware ESLint configuration for TypeScript
__INLINE_CODE_33__	ESLint configuration for Node.js JavaScript
__INLINE_CODE_34__	ESLint configuration for Node.js TypeScript
__INLINE_CODE_35__	Type-aware ESLint configuration for Node.js TypeScript
__INLINE_CODE_36__	ESLint configuration for Browser JavaScript
__INLINE_CODE_37__	ESLint configuration for Browser TypeScript
__INLINE_CODE_38__	Type-aware ESLint configuration for Browser TypeScript
__INLINE_CODE_39__	ESLint configuration for Bun JavaScript
__INLINE_CODE_40__	ESLint configuration for Bun TypeScript
__INLINE_CODE_41__	Type-aware ESLint configuration for Bun TypeScript
__INLINE_CODE_42__	ESLint overrides for Jest test files
__INLINE_CODE_43__	ESLint overrides for Vitest test files
__INLINE_CODE_44__	ESLint configuration for React with JSX
__INLINE_CODE_45__	ESLint configuration for React with TSX
__INLINE_CODE_46__	Biome configuration for formatting, linting, and import organization
__INLINE_CODE_47__	Bun test configuration template with coverage enabled
__INLINE_CODE_48__	Commitlint configuration for Conventional Commits
__INLINE_CODE_49__	EditorConfig template for common project files
__INLINE_CODE_50__	Jest configuration for TypeScript test projects
__INLINE_CODE_51__	Vitest configuration for TypeScript test projects
__INLINE_CODE_52__	Markdownlint configuration for Markdown docs
__INLINE_CODE_53__	Stylelint configuration for CSS projects
__INLINE_CODE_54__	TypeDoc configuration for TypeScript API docs
__INLINE_CODE_55__	Prettier configuration

Included Rules

Code Quality

• Curly braces - Requires curly braces for all control statements (__INLINE_CODE_56__)
• Strict equality - Requires __INLINE_CODE_57__ and __INLINE_CODE_58__ (__INLINE_CODE_59__)
• Unused variables - Warns on unused variables, ignoring args prefixed with __INLINE_CODE_60__
• Destructuring - Prefer destructuring object properties and array items before using them
• Environment variables - Prefer destructuring __INLINE_CODE_61__ over bracket notation
• Async flow - Requires __INLINE_CODE_62__/__INLINE_CODE_63__ instead of __INLINE_CODE_64__ and __INLINE_CODE_65__

Examples:

__CODE_BLOCK_56__ __CODE_BLOCK_57__ __CODE_BLOCK_58__ __CODE_BLOCK_59__ __CODE_BLOCK_60__ __CODE_BLOCK_61__

Formatting and import organization are handled by Biome, not ESLint.

ESLint Plugins

• __INLINE_CODE_66__ - ESLint recommended rules
• __INLINE_CODE_67__ - TypeScript support
• __INLINE_CODE_68__ - React rules
• __INLINE_CODE_69__ - React Hooks rules
• __INLINE_CODE_70__ - JSX accessibility

Biome Configuration

• Semicolons enabled
• Single quotes
• Double quotes in JSX attributes
• Print width: 100 characters
• Tab width: 2 spaces
• Trailing commas: all
• Arrow parens: always
• Import organization enabled
• Block statements required for control flow (__INLINE_CODE_71__)

Examples:

__CODE_BLOCK_62__ __CODE_BLOCK_63__

Development

__CODE_BLOCK_64__

Changelog

See CHANGELOG.md for details.

License

MIT Ivan