js-lint

A batteries-included, TypeScript-aware linting CLI and ESLint flat config bundle for use in Matrix AI JavaScript/TypeScript projects.

• Type-aware linting powered by @typescript-eslint using one or more tsconfig.json files
• Built-in support for React, Tailwind, JSX a11y, Prettier, and Matrix AI custom rules
• Supports Prettier formatting for Markdown, ShellCheck for shell scripts, and nixfmt for Nix files
• Single command to lint JavaScript/TypeScript, Markdown, shell scripts, and Nix files
• Customizable via matrixai-lint-config.json and extensible with your own ESLint config
• CLI options to override config and enable auto-fix

Installation

npm install --save-dev @matrixai/lint

Usage

CLI

matrixai-lint

With autofix:

matrixai-lint --fix

CLI Options

| Flag | Description | | ------------------------ | ---------------------------------------------------------------------------- | | (no flag) | Uses built-in Matrix AI ESLint config | | --fix | Enables auto-fixing via ESLint and Prettier | | --user-config | Uses detected eslint.config.[js,mjs,cjs,ts] from the project root if found | | --eslint-config <path> | Explicitly use a custom ESLint config file | | --eslint <targets> | ESLint targets (files, roots, or globs); implies ESLint domain selection | | --markdown <targets> | Markdown targets (files, roots, or globs); implies markdown domain selection | | --nix <targets> | Nix targets (files, roots, or globs); implies nix domain selection | | --shell <targets> | Shell targets (files, roots, or globs); implies shell domain selection | | --domain <id...> | Run only selected domains (eslint, shell, markdown, nix) | | --skip-domain <id...> | Skip selected domains (eslint, shell, markdown, nix) | | --list-domains | Print available domains and short descriptions, then exit 0 | | --explain | Print per-domain decision details before execution | | -v, --verbose | Increase log verbosity (repeat for more detail) |

Domain selection behavior:

• With no selectors and no domain-specific target flags, all built-in domains run by default.
• Passing --eslint and/or --shell implies explicit domain selection from those flags.
  • --eslint ... runs ESLint only.
  • --shell ... runs shell only.
  • Passing both runs both.
• Passing --markdown implies markdown domain selection.
  • --markdown ... runs markdown only.
  • Combined with other target flags, only those targeted domains run.
• Passing --nix implies nix domain selection.
  • --nix ... runs nix only.
  • Combined with other target flags, only those targeted domains run.
• shellcheck is optional only for default auto-run shell execution.
  • If shell is explicitly requested (--shell ... or --domain shell), missing shellcheck is a failure.
• nixfmt is optional only for default auto-run nix execution.
  • If nix is explicitly requested (--nix ... or --domain nix), missing nixfmt is a failure.
• --shell accepts target paths and glob patterns.
  • Directories are used as roots.
  • File paths and glob patterns are reduced to search roots, then *.sh files are discovered under those roots.
• --markdown accepts target paths and glob patterns.
  • Directories are used as roots.
  • File paths and glob patterns are reduced to search roots, then *.md / *.mdx files are discovered under those roots.
  • Root-level README.md and AGENTS.md are always auto-included when present.
• --nix accepts target paths and glob patterns.
  • Directories are used as roots.
  • File paths and glob patterns are reduced to search roots, then *.nix files are discovered under those roots.
  • By default, nix domain scope is flake.nix, shell.nix, default.nix, and nix/**/*.nix.
  • When --nix is provided, explicit nix targets replace these defaults.

Targeted workflows

• Only ESLint on a subset of files:

  matrixai-lint --eslint "src/**/*.{ts,tsx}" --domain eslint

• Only shell scripts under specific roots:

  matrixai-lint --shell scripts packages/*/scripts

• Markdown only:

  matrixai-lint --domain markdown

• Markdown only under selected roots:

  matrixai-lint --markdown standards templates README.md

• Nix only (default nix scope):

  matrixai-lint --domain nix

• Nix only under selected roots/patterns:

  matrixai-lint --nix nix modules flake.nix

• Mixed scoped run (ESLint + shell only):

  matrixai-lint --eslint "src/**/*.{ts,tsx}" --shell scripts

Examples

matrixai-lint --fix
matrixai-lint --user-config
matrixai-lint --eslint-config ./eslint.config.js --fix
matrixai-lint --eslint "src/**/*.{ts,tsx}" --shell scripts
matrixai-lint --markdown standards templates README.md
matrixai-lint --nix nix flake.nix
matrixai-lint --domain eslint markdown
matrixai-lint --domain nix
matrixai-lint --skip-domain markdown
matrixai-lint --list-domains
matrixai-lint --explain --domain eslint
matrixai-lint -v -v --domain markdown

ESLint config (ESM / NodeNext)

matrixai-lint ships an ESLint Flat Config array and types for TypeScript projects configured as NodeNext.

Default import

// eslint.config.js
import { config } from '@matrixai/lint';

export default config;

Explicit subpath import

// eslint.config.js
import matrixai from '@matrixai/lint/configs/eslint.js';

export default matrixai;

Lint configuration file

The linter is TypeScript-aware and requires a tsconfig.json to determine which files to lint and how to parse them. By default it looks for tsconfig.json in the project root and uses the include/exclude entries.

If your project uses more than one tsconfig.json or does not have one at the root, configure the linter using a matrixai-lint-config.json file at the root.

This config uses a versioned schema and must explicitly declare "version": 2:

{
  "version": 2,
  "root": ".",
  "domains": {
    "eslint": {
      "tsconfigPaths": [
        "./tsconfig.base.json",
        "./packages/core/tsconfig.json"
      ],
      "forceInclude": ["scripts", "src/overrides"]
    }
  }
}

| Field | Type | Description | | ------------------------------ | ---------- | ----------------------------------------------------------------------------------------- | | version | 2 | Required schema version marker | | root | string | Optional lint root (defaults to .). tsconfigPaths are resolved relative to this root. | | domains.eslint.tsconfigPaths | string[] | One or more paths to tsconfig.json files | | domains.eslint.forceInclude | string[] | Paths to always include, even if excluded by tsconfig (must be included by at least one) |

Note: If a path in forceInclude is not included in any of the tsconfigPaths, TypeScript will throw a parsing error.

Public API

Supported imports:

• @matrixai/lint: named export config; types MatrixAILintCfg, RawMatrixCfg, CLIOptions.
• @matrixai/lint/configs/eslint.js: default export of the ESLint Flat Config array (same shape as config).
• @matrixai/lint/configs/prettier.config.js: reusable Prettier options object.

The exported config is intended as a composable base preset for downstream eslint.config.js files, not as an internal-only implementation detail.

Any package import path not listed above is internal and not a stable public API.

Contributing

Golden commands:

• npm run build
• npm run lint
• npm run lintfix
• npm run docs

Notes:

• npm run lint and npm run lintfix invoke npm run prepare first so the compiled CLI in dist/bin/matrixai-lint.js stays up to date while keeping TypeScript incremental rebuilds fast.

For the authoritative contributor guidance see AGENTS.md.

Docs: https://matrixai.github.io/js-lint/

Publishing

Publishing is handled automatically by the staging pipeline.

Prerelease:

# npm login
npm version prepatch --preid alpha # premajor/preminor/prepatch
git push --follow-tags

Release:

# npm login
npm version patch # major/minor/patch
git push --follow-tags

Manually:

# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags