@encoura/eslint-config

ESLint Config

Encoura's preferred configs for TypeScript, Prettier, ESLint, CommitLint, and MarkdownLint.

Getting Started

Install this package, ESLint, husky, and lint-staged as dev dependencies:

npm install --save-dev @encoura/eslint-config eslint@^10 husky lint-staged

Configure husky by adding the following to your package.json file:

...
"scripts": {
  ...
  "prepare": "husky",
  ...
},
...

Configure CommitLint

To configure CommitLint, create a commitlint.config.js file in the root of your project that contains the following:

module.exports = require('@encoura/eslint-config/commitlint.config');

This will allow CommitLint to discover the configuration this repository provides from within your node_modules folder.

By default the Encoura commitlint expects a commit message in the following format:

[XXX-###]: Subject where XXX-### is a work item id, e.g., WEB-1

The commit message may also be in the form of git's standard merge commit format.

Configure ESLint

To configure ESLint, add the following to your eslint.config.js and package.json files. This package supports ESLint 10's flat config system. This repository develops and validates the config on Node 24.

Five upstream packages still declare peer ranges that exclude ESLint 10: Airbnb, Airbnb Base, Import, React, and JSX accessibility. Their original implementations and rule names are retained. The build bundles those packages and their locked production dependencies into the published artifact. It widens only their ESLint peer metadata to include v10 and Airbnb's React Hooks peer metadata to include v7.

These are package-local compatibility patches, not upstream declarations of support. The existing @eslint/compat adapters handle legacy rule APIs. Consumers need no peer overrides or --legacy-peer-deps. Tests install the packed artifact with strict peers, compare complete rule inventories, and verify that bundled implementation files match the installed originals.

Bundled dependencies are fixed by this package's lockfile. Their updates require a new package build and release. Use npm ci before release builds. Remove each compatibility patch when its upstream package supports these peer versions.

const createConfig = require('@encoura/eslint-config');

module.exports = createConfig({
  nextRootDir: __dirname,
  resolverProject: ['tsconfig.json'],
  tsconfigRootDir: __dirname,
});

For back-end (Nest.js) projects:

const createConfig = require('@encoura/eslint-config/nest');

module.exports = createConfig({
  resolverProject: ['tsconfig.json'],
  tsconfigRootDir: __dirname,
});

...
"lint-staged": {
  ...
  "*.{js,jsx,ts,tsx}": "eslint",
  ...
},
...

Breaking Changes In v4

• ESLint config consumers must use ESLint 10 flat config. Legacy .eslintrc extends: ['@encoura/eslint-config'] and extends: ['@encoura/eslint-config/nest'] usage is no longer supported. Create an eslint.config.js file and call the exported config factory instead.
• Install eslint@^10 directly in consuming projects. This package declares ESLint 10 as a peer so the project-level eslint CLI resolves to the expected major version.
• The published jest.config.js export and Jest-related dependencies were removed. Projects that imported @encoura/eslint-config/jest.config should own their Jest or Vitest config locally.
• Jest-specific test linting is no longer enabled by this shared ESLint config. Test files still receive the shared TypeScript/React overrides, but Vitest projects no longer inherit Jest rules.
• eslint-plugin-disable is no longer bundled. The shared config did not enable any disable/* rules; projects that used that package transitively should add their own dependency.

Configure MarkdownLint

To configure MarkdownLint, add the following to your package.json file. This will allow MarkdownLint to discover the configuration this repository provides from within your node_modules folder, and will check your *.md files for infractions every time you create a new commit:

...
"lint-staged": {
  ...
  "*.{md}": "markdownlint --config node_modules/@encoura/eslint-config/markdownlint.config.json",
  ...
},
...

Configure Prettier

To configure prettier, create a .prettierrc.js file in the root of your project that contains the following:

module.exports = require('@encoura/eslint-config/prettier.config');

This will allow Prettier to discover the configuration this repository provides from within your node_modules folder.

Next, add the following to your package.json file so that prettier will check your files for infractions every time you create a new commit:

...
"lint-staged": {
  ...
  "*.{js,jsx,json,md,ts,tsx}": [
    "prettier --write",
    "git add"
  ]
  ...
},
...

Configure TypeScript

To configure TypeScript, add the following to your tsconfig.json file. This will allow TypeScript to discover the configuration this repository provides from within your node_modules folder:

...
"extends": "node_modules/@encoura/eslint-config/tsconfig.json",
...

Dependency Upgrade Notes

See UPGRADE-NOTES.md for security fixes, tooling compatibility changes, consumer migration steps, and validation commands.

Local Development

npm Scripts

There are several npm scripts at your disposal during local development. Here are some of the more important ones:

Script	Description
npm test	Run all validation checks.
npm run testjs	Lint JavaScript files with the shared ESLint config.
npm run testts	Lint TypeScript files with the shared ESLint config.
npm run testmd	Lint Markdown files with the shared MarkdownLint config.
npm run test:prettier	Check formatting with Prettier.
npm run test:tsconfig	Validate the shared TypeScript config.
npm run test:unit	Run unit tests for the exported config factories.

Release Process

When your code changes are ready, it's time to publish a new patch, minor, or major release. Maintainers typically squash pull requests when merging, so the PR title becomes the squash commit title and is the source of truth for patch and minor release detection.

1. Make a PR (or mark your draft PR as ready for review).

2. Choose a public-safe PR title that lets Semantic Release know if this should yield a new patch, minor, or major release:

   • If you expect the merging of your PR to result in a new patch release, start your PR title with fix:.
   • If you expect the merging of your PR to result in a new minor release, start your PR title with feat:.
   • If you expect the merging of your PR to result in a new major release, see #3 below for details.
   • If you expect the merging of your PR to skip the creation of a new release, you can start your PR title with build: (for build changes), chore: (for basic maintenance), docs: (for documentation updates), or simply do not use any of the above keyword prefixes.

3. If the pull request should create a new major version release, the string BREAKING CHANGE: must be included in at least one commit message's footer (see docs) — Semantic Release's commit analyzer does not use the PR title in determining major releases.

   You can either manually add BREAKING CHANGE: to the commit footer after pressing "Merge Pull Request"/"Squash and Merge" in your PR (in the "optional extended description" field). Alternatively, if you're merging the PR by creating a new merge commit, ensure that at least one of the source commits' messages has BREAKING CHANGE: in its footer. Note that to accomplish this you may need to commit with the --no-verify flag to bypass commitlint.

4. Once your PR is merged, Semantic Release will pick it up and initiate the automated release process. If it detects that it should create a release (based on the above), it will. Otherwise, it won't!