eslint-config-spartan v1.0.0

ESLint Config Spartan

eslint-config-spartan is an opinionated eslint configuration with separate configs (called mixins) for various eslint plugins.

Details:

• Config Format: Flat config No support for the eslintrc format.
• ESLint Version: ^9.22.0
• Module Type: ESM and CJS

Table of Contents

• ESLint Config Spartan
  • Table of Contents
  • What's New
  • Philosophy
  • Install
  • Build Config
  • Utilities
    • Files
    • Merge Config
  • Mixins
    • Angular
    • Chai
    • Common Js
    • Cypress
    • Google Apps Script
    • i18n JSON
    • i18next
    • Jest
    • Jest DOM
    • JS Doc
    • JSX Accessibility
    • Markdown and MDX
    • Mocha
    • Naming Convention
    • NextJs
    • Playwright
    • Prettier
    • Promise
    • React
    • Regular Expressions (RegExp)
    • Storybook
    • Tailwind CSS
    • TanStack Query
    • Testing Library / React
    • Type Enabled
    • Unicorn
    • Vitest
  • Remark
    • Usage
    • Usage With Prettier
  • License

What's New

Check out the GitHub Releases page for the latest release notes.

Philosophy

For the most part, eslint-config-spartan aims to be opinionated in areas that promote good practices and prevent common pitfalls and/or foot-guns. eslint-config-spartan tries not to be over opinionated in areas that are not related to preventing errors; however, some of the opinions are also chosen for the sake of consistency, especially when auto-fix rules are available to help maintain the consistency without extra burden for the writer.

eslint-config-spartan also strongly recommends the use of code-formatting tools, such as prettier. Such tools help to remove some mental load from the writer. They also assist the reader, where the consistency can help to more quickly parse though code. This can also help with code review, since the reviewer can focus more of their energy on the functionality of the code. Lastly, these can help to reduce diffs in git commits, which also helps with code review, since it's easier to focus in on what has actually changed, rather than what was simply reformatted.

Install

npm install --save-dev eslint eslint-config-spartan

Build Config

The primary export of this config is a function called buildConfig. This function returns the base config and can receive other configs or mixins as inputs, which are included in the final config array output.

!NOTE

This config does not enable any rules from typescript-eslint that require type information. These rules are extremely useful, however they can cause performance issue in some code bases, so they have been separated into their own mixin to be applied as separately. See Linting with Type Information for details.

The base config includes the following plugins:

• The @eslint/js rules have no prefix
• The typescript-eslint rules are prefixed with @typescript-eslint
• The @stylistic/eslint-plugin rules are prefixed with @stylistic
• The eslint-plugin-import rules are prefixed with import
• The eslint-plugin-security rules are prefixed with security
• The eslint-plugin-unused-imports rules are prefixed with unused-imports
• The eslint-plugin-typescript-enum rules are prefixed with typescript-enum

Example:

// eslint.config.js
import { buildConfig } from 'eslint-config-spartan';
import { jsDoc, prettier, typeChecked } from 'eslint-config-spartan/mixins';
import { files } from 'eslint-config-spartan/utils';

export default buildConfig(
  typeChecked({
    parserOptions: {
      tsconfigRootDir: __dirname,
      project: './tsconfig.json',
    },
  }),
  jsDoc,
  {
    name: 'root/scripts',
    files: [`scripts/${files.jsTsNoX}`],
    rules: {
      '@typescript-eslint/no-magic-numbers': 'off',
      'security/detect-non-literal-fs-filename': 'off',
    },
  },
  prettier,
  { ignores: ['coverage/', 'reports/', '.vscode/', 'dist/'] },
);

Utilities

Files

The files utility contains a set of commonly used glob patterns for various file names and extensions that may require linting. These can be used as items in the files or ignores fields in a flat config object.

Example:

import { files } from 'eslint-config-spartan/utils';

const config = {
  files: [files.jsTs, files.markdown],
  rules: {
    // ... Additional rules
  },
};

Merge Config

The mergeConfig utility combines the given config options into an array of single configs. Each input can be an individual config, a function that returns a config (or array of configs), or an array of the previous types.

This would be useful in a monorepo where there is a main eslint.config.js file that exports a base config, which can be extended by using this utility.

Example:

// eslint.config.js
import base from '../../eslint.config.js';
import { jsDoc, mdx, nextJs, prettier, react } from 'eslint-config-spartan/mixins';
import { files, mergeConfig } from 'eslint-config-spartan/utils';

export default mergeConfig(base, jsDoc, react, nextJs, mdx({ files: [files.mdx] }), prettier);

Mixins

Mixins are functions which return an eslint config. Most of the mixins import a plugin along with some configured rules. The mixins have some inputs for convenience, i.e. choosing which files the mixin applies to, but the rules and config can be overridden in a subsequent config in the final config array.

Angular

The angular mixin creates an ESLint config for @angular-eslint/eslint-plugin and @angular-eslint/eslint-plugin-template to assist with using the Angular framework.

Rule Prefixes:

• The @angular-eslint/eslint-plugin rules are prefixed with @angular-eslint
• The @angular-eslint/eslint-plugin-template rules are prefixed with @angular-eslint/template

import { angular } from 'eslint-config-spartan/mixins';

!TIP

To see linting errors and apply auto-fix rules on save for .html files in VS Code, add the html language to the validate list in the VS Code settings for eslint.

// .vscode/settings.json
{
  "eslint.validate": ["html"]
}

Chai

The chai mixin creates an ESLint config for eslint-plugin-chai-friendly and eslint-plugin-chai-expect to assist with using the Chai Assertion Library.

Rule Prefixes:

• The eslint-plugin-chai-expect rules are prefixed with chai-expect
• The eslint-plugin-chai-friendly rules are prefixed with chai-friendly

!NOTE

Note: This config also adjusts some @typescript-eslint rules to make them more helpful for test files.

import { chai } from 'eslint-config-spartan/mixins';

Common Js

The commonJs mixin creates an ESLint config for common js files.

This config is included in buildConfig and applied to files with common js extensions. This can be used to apply the config to .js files which are known to be common js.

Note: This config also adjusts some @typescript-eslint and unicorn rules that conflict with common js globals. This config should be added after the configs for these rules.

import { commonJs } from 'eslint-config-spartan/mixins';

Cypress

The cypress mixin creates an ESLint config for eslint-plugin-cypress to assist with using the Cypress Testing Framework.

Rule Prefixes:

• The eslint-plugin-cypress rules are prefixed with cypress

!NOTE

Note: This config also adjusts some @typescript-eslint rules to make them more helpful for test files.

import { cypress } from 'eslint-config-spartan/mixins';

Google Apps Script

The googleAppsScript mixin creates an ESLint config for eslint-plugin-googleappsscript which contains globals for the Google Apps Script environment.

Rule Prefixes:

• The eslint-plugin-googleappsscript does not contain any rules.

import { googleAppsScript } from 'eslint-config-spartan/mixins';

i18n JSON

The i18nJson mixin creates an ESLint config for eslint-plugin-i18n-json to assist with maintaining json-based i18n translation files.

Rule Prefixes:

• The eslint-plugin-i18n-json rules are prefixed with i18n-json

import { i18nJson } from 'eslint-config-spartan/mixins';

export default buildConfig(
  i18nJson({
    files: ['src/translations/*.json'],
    identicalKeysFilePath: path.resolve('src/translations/en.json'),
  }),
);

!TIP

To see linting errors and apply auto-fix rules on save for .json files in VS Code, add the json language to the validate list in the VS Code settings for eslint.

// .vscode/settings.json
{
  "eslint.validate": ["json"]
}

i18next

The i18next mixin creates an ESLint config for eslint-plugin-i18next to assist with using the i18next internationalization library.

Rule Prefixes:

• The eslint-plugin-i18next rules are prefixed with i18next

import { i18next } from 'eslint-config-spartan/mixins';

Jest

The jest mixin creates an ESLint config for eslint-plugin-jest to assist with using the jest testing framework.

Rule Prefixes:

• The eslint-plugin-jest rules are prefixed with jest

!NOTE

Note: This config also adjusts some @typescript-eslint rules to make them more helpful for test files.

import { jest } from 'eslint-config-spartan/mixins';

Jest DOM

The jestDom mixin creates an ESLint config for eslint-plugin-jest-dom to assist with using the jest-dom element matchers.

Rule Prefixes:

• The eslint-plugin-jest-dom rules are prefixed with jest-dom

import { jestDom } from 'eslint-config-spartan/mixins';

JS Doc

The jsDoc mixin creates an ESLint config for eslint-plugin-jsdoc to assist with writing JS Doc comments.

This creates three configurations, one to apply the recommended rules to js files, another to apply the recommended rules to ts files and a third to configure rules across both sets of files.

Rule Prefixes:

• The eslint-plugin-jsdoc rules are prefixed with jsdoc

import { jsDoc } from 'eslint-config-spartan/mixins';

JSX Accessibility

The jsxA11y mixin creates an ESLint config for eslint-plugin-jsx-a11y to assist with accessibility when using JSX templates.

Rule Prefixes:

• The eslint-plugin-jsx-a11y rules are prefixed with jsx-a11y.

import { jsxA11y } from 'eslint-config-spartan/mixins';

Markdown and MDX

The mdx mixin creates an ESLint config for eslint-plugin-mdx to assist with writing MDX and markdown files, as well as code blocks within markdown files. This also adds support for using remark-lint rules within those files. See the Remark section of this document for more details.

This creates two configurations, one to apply the recommended config for .mdx, .md, and .markdown files, and another to apply the recommended config to code blocks in those files.

!NOTE

• This config also adjusts some rules to accommodate mdx syntax and code blocks.
• The typescript-eslint rules that require type information cannot be used within code blocks, since the parser cannot parse the blocks within the files.

Rule Prefixes:

• The eslint-plugin-mdx rules are prefixed with mdx.

!TIP

To apply rules to the code blocks, the format for selecting the code block type is by first selecting the markdown file itself, then adding the block type to the path. e.g. *.{md,mdx}/js to select all js code blocks within .md or .mdx files.

import { mdx } from 'eslint-config-spartan/mixins';

Mocha

The mocha mixin creates an ESLint config for eslint-plugin-mocha to assist with using the Mocha test framework.

!NOTE

Note: This config also adjusts some @typescript-eslint rules to make them more helpful for test files.

Rule Prefixes:

• The eslint-plugin-mocha rules are prefixed with mocha

import { mocha } from 'eslint-config-spartan/mixins';

Naming Convention

The namingConvention mixin adds configuration for the @typescript-eslint/naming-convention rule. Note: This mixin requires the @typescript-eslint plugin to be already configured.

import { namingConvention } from 'eslint-config-spartan/mixins';

NextJs

The nextJs mixin creates an ESLint config for @next/eslint-plugin-next to assist with Next.js application development.

Rule Prefixes:

• The eslint-plugin-next rules are prefixed with @next/next

import { nextJs } from 'eslint-config-spartan/mixins';

Playwright

The playwright mixin creates an ESLint config for eslint-plugin-playwright to assist with using the Playwright framework.

Rule Prefixes:

• The eslint-plugin-playwright rules are prefixed with playwright

import { playwright } from 'eslint-config-spartan/mixins';

Prettier

The prettier mixin creates an ESLint config for disabling rules which may interfere or conflict with Prettier.

!IMPORTANT

This config must come LAST in the list of configurations so that it can override other configs.

!NOTE

This config essentially re-exports eslint-config-prettier with some adjustments. It also disables rules for @stylistic/eslint-plugin.

import { prettier } from 'eslint-config-spartan/mixins';

Promise

The promise mixin creates an ESLint config for eslint-plugin-promise to assist with encouraging good practices when using JS Promises.

Rule Prefixes:

• The eslint-plugin-promise rules are prefixed with promise

import { promise } from 'eslint-config-spartan/mixins';

React

The react mixin creates an ESLint config for eslint-plugin-react and eslint-plugin-react-hooks to assist with React application development.

Rule Prefixes:

• The eslint-plugin-react rules are prefixed with react
• The eslint-plugin-react-hooks rules are prefixed with react-hooks

import { react } from 'eslint-config-spartan/mixins';

Regular Expressions (RegExp)

The regExp mixin creates an ESLint config for eslint-plugin-regexp to assist with encouraging good practices when using JS Regular Expressions.

Rule Prefixes:

• The eslint-plugin-regexp rules are prefixed with regexp

import { regExp } from 'eslint-config-spartan/mixins';

Storybook

The storybook mixin creates an ESLint config for eslint-plugin-storybook to assist with component development in Storybook.

Rule Prefixes:

• The eslint-plugin-storybook rules are prefixed with storybook

import { storybook } from 'eslint-config-spartan/mixins';

Tailwind CSS

The tailwindCss mixin creates an ESLint config for eslint-plugin-tailwindcss to assist with using the Tailwind CSS framework.

Rule Prefixes:

• The eslint-plugin-tailwindcss rules are prefixed with tailwindcss

import { tailwindCss } from 'eslint-config-spartan/mixins';

TanStack Query

The tanStackQuery mixin creates an ESLint config for @tanstack/eslint-plugin-query to assist with using the TanStack Query hook for fetching, caching and updating asynchronous data in React, Solid, Svelte and Vue.

Rule Prefixes:

• The @tanstack/eslint-plugin-query rules are prefixed with @tanstack/query

import { tanStackQuery } from 'eslint-config-spartan/mixins';

Testing Library / React

The testingLibraryReact mixin creates an ESLint config for eslint-plugin-testing-library to assist with component testing using Testing Library.

Rule Prefixes:

• The eslint-plugin-testing-library rules are prefixed with testing-library

import { testingLibraryReact } from 'eslint-config-spartan/mixins';

Type Enabled

The typeEnabled mixin creates an eslint config with type-enabled rules for typescript-eslint. It requires an external config to enable the @typescript-eslint plugin itself since it only includes rules. i.e. it's meant to bs used with the base config created with Build Config. It also disables base eslint rules that are replaced with the equivalent typescript-eslint rules.

!NOTE

Note: This config also adds an ignores property to prevent these rules from being applied to code blocks within markdown files when the mdx mixin is being used since the parser cannot access that code.

Rule Prefixes:

• The typescript-eslint rules are prefixed with @typescript-eslint

import { typeEnabled } from 'eslint-config-spartan/mixins';

Unicorn

The unicorn mixin creates an ESLint config for eslint-plugin-unicorn which contains miscellaneous rules.

Rule Prefixes:

• The eslint-plugin-unicorn rules are prefixed with unicorn

import { unicorn } from 'eslint-config-spartan/mixins';

Vitest

The vitest mixin creates an ESLint config for @vitest/eslint-plugin to assist with using the Vitest Testing Framework.

Rule Prefixes:

• The @vitest/eslint-plugin rules are prefixed with vitest

!NOTE

Note: This config also adjusts some @typescript-eslint rules to make them more helpful for test files.

import { vitest } from 'eslint-config-spartan/mixins';

Remark

Since eslint-plugin-mdx supports additional linting of markdown/mdx files using remark, we have included a remark lint preset.

Usage

To use the included preset:

1. Create the remark rc file at the root of your project (i.e. .remarkrc.mjs).
2. Import the remark preset.
3. Export the config with the preset included.

// .remarkrc.mjs
import { remark } from 'eslint-config-spartan/remark';

export default { plugins: [remark] };

!NOTE

The Markdown and MDX mixin is already configured to run remark-lint on the markdown and mdx files. Once a remarkrc file is available, it will start reporting remark-lint errors through ESLint.

Usage With Prettier

Similarly to ESLint, many of the remark-lint rules conflict with the prettier formatting. We also include a prettier preset which disables the conflicting rules. As with the ESLint prettier config, the prettier preset should also be included at the end of the plugins list.

// .remarkrc.mjs
import { remark, remarkPrettier } from 'eslint-config-spartan/remark';

export default { plugins: [remark, remarkPrettier] };

License

The scripts and documentation in this project are released under the MIT License as defined by the Open Source Initiative.