Defense Unicorn Recommended Linter Configurations

This repository is ensures organizational code quality with a standard set of linter rules for Typescript & Javascript code. At present, use of the rulesets defined in this repository are not mandated.

Usage

Add this package to your project as a devDependency with:

npm install @defenseunicorns/eslint-config --save-dev

Two framework-agnostic rulesets are provided: recommended and strict. These rulesets work with any TypeScript or JavaScript project regardless of framework (React, Vue, Node.js, Express, etc.).

recommended Ruleset

The recommended ruleset provides a balanced set of linting rules suitable for most projects across the organization. Use this ruleset for general TypeScript/JavaScript projects. For now, this ruleset just warns on the eqeqeq rule.

Configure your eslint.config.mjs like this:

import { recommended } from '@defenseunicorns/eslint-config';

export default [...recommended];

strict Ruleset

The strict ruleset enforces more rigorous code quality standards and is ideal for projects that require higher consistency and fewer exceptions. For now, this ruleset just errors on the eqeqeq rule.

Configure your eslint.config.mjs like this:

import { strict } from '@defenseunicorns/eslint-config';

export default [...strict];

Overriding Rules

[!CAUTION] Overriding rules from this package defeats the purpose of the package to ensure org-wide code-quality. However, if you must override a rule, here's how:

In this example, eqeqeq is defined in the recommended ruleset. A similar pattern can be used for any of the eslint configuration options.

import { recommended } from '@defenseunicorns/eslint-config';

export default [
  ...recommended,
  {
    rules: {
      eqeqeq: 'off',
    },
  },
];

Adopting ESlint in All Repos

Apply linter configurations to N repos

To apply a standard config setting to a list of repos, use migrate-eslint.ts.

For example, npx ts-node -P draft/tsconfig.json migration/migrate-eslint.ts performs a migration process. You can use pepr-excellent-examples as a reference point on performing bulk-migrations.

If linting has not been previously configured, the repo will be initialized with an empty ruleset to be filled in later. If a linting ruleset exists on versions earlier that 9.X, then @eslint/migrate-config will migrate the config. If a linting ruleset exists on versions on 9.X, then eslint will be called.

Results of the eslint command are stored in each repository at /eslint-migration.log.

Common errors and warnings

(node:59582) [MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of file:///[...]/eslint.config.js?mtime=1740695085181 is not specified and it doesn't parse as CommonJS.
Reparsing as ES module because module syntax was detected. This incurs a performance overhead.
To eliminate this warning, add "type": "module" to /[...]/package.json.

Resolution: Add "type": "module" to package.json.

  0:0  error  Parsing error: /[...]/*.js was not found by the project service. Consider either including it in the tsconfig.json or including it in allowDefaultProject

Resolution: Add "**/*.js" to include in tsconfig.json AND add "allowJs": true to compilerOptions in tsconfig.json.

  0:0  error  Parsing error: "parserOptions.project" has been provided for @typescript-eslint/parser.
The file was not found in any of the provided project(s): *.[js|mjs]

Resolution: Add those file paths to the ignores block of the eslint.config.mjs file.

  9:34  error  Parsing error: Unexpected token :

Resolution: Ensure that tsParser from @typescript-eslint/parser is in use. See sample languageOptions:

import tsParser from '@typescript-eslint/parser'
[...]
  {
    languageOptions: {
      parser: tsParser,
    }
  },
[...]

Known Issues

Projects with multiple configs (uncommon)