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 theeslintrc
format. - ESLint Version:
^9.22.0
- Module Type:
ESM
andCJS
Table of Contents
- ESLint Config Spartan
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.
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';
To see linting errors and apply auto-fix rules on save for
.html
files in VS Code, add thehtml
language to thevalidate
list in the VS Code settings foreslint
.// .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 withchai-expect
- The
eslint-plugin-chai-friendly
rules are prefixed withchai-friendly
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 withcypress
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 withi18n-json
import { i18nJson } from 'eslint-config-spartan/mixins';
export default buildConfig(
i18nJson({
files: ['src/translations/*.json'],
identicalKeysFilePath: path.resolve('src/translations/en.json'),
}),
);
To see linting errors and apply auto-fix rules on save for
.json
files in VS Code, add thejson
language to thevalidate
list in the VS Code settings foreslint
.// .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 withi18next
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 withjest
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 withjest-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 withjsdoc
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 withjsx-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.
- 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 withmdx
.
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 alljs
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: 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 withmocha
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 withplaywright
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.
This config must come LAST in the list of configurations so that it can override other configs.
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 withpromise
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 withreact
- The
eslint-plugin-react-hooks
rules are prefixed withreact-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 withregexp
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 withstorybook
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 withtailwindcss
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 withtesting-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: 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 withunicorn
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 withvitest
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:
- Create the remark rc file at the root of your project (i.e.
.remarkrc.mjs
). - Import the
remark
preset. - Export the config with the preset included.
// .remarkrc.mjs
import { remark } from 'eslint-config-spartan/remark';
export default { plugins: [remark] };
The Markdown and MDX mixin is already configured to run
remark-lint
on the markdown and mdx files. Once aremarkrc
file is available, it will start reportingremark-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.
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago