eslint-config-async

3.1.0 verified Sat Apr 25 auth: no javascript

A shareable ESLint config (v3.1.0) for writing better asynchronous JavaScript and TypeScript code. It provides a curated set of rules to avoid common async pitfalls (e.g., unhandled promises, missing await, improper error handling) based on the author's article. Requires ESLint v9 and Node.js ^18.18.0 || ^20.9.0 || >=21.1.0. Key differentiators: focused solely on async patterns, built-in TypeScript support via typescript-eslint, and flat config only (no .eslintrc support in v3).

Common errors

error Error: Cannot find module 'eslint-config-async' ↓

cause Package not installed or incorrect import path.

fix

Run: npm install --save-dev eslint-config-async

error Require of ES Module eslint-config-async not supported. ↓

cause Using require() in an ESM project or wrong config file extension.

fix

Use import asyncConfig from 'eslint-config-async' or rename file to .cjs.

error Configuration for rule 'no-return-await' is invalid: Value 'error' is the wrong type. ↓

cause Using an old eslint-config-async version with ESLint v9 which removed the rule.

fix

Upgrade to eslint-config-async@3.1.0 which removed 'no-return-await'.

Warnings

breaking v3 requires ESLint v9 and flat config (.eslintrc.* not supported). ↓

fix Migrate to eslint.config.js and use the array-based flat config syntax shown in the README.

breaking v3 replaces eslint-config-node (unmaintained) with eslint-config-n and moves it from peer to direct dependency. ↓

fix Remove eslint-plugin-node from devDependencies; eslint-config-async now includes eslint-plugin-n.

breaking v3 merges multiple config files into a single file with named exports; old extends patterns fail. ↓

fix Use named exports: asyncConfig.base, asyncConfig.node, asyncConfig.typescript.

breaking v2 to v3: typescript-eslint v8 replaces @typescript-eslint/parser and @typescript-eslint/eslint-plugin. ↓

fix Install typescript-eslint and use tseslint.configs.base instead of parser/plugin.

gotcha Non-TypeScript users must not use asyncConfig.typescript; it will cause errors without typescript-eslint. ↓

fix Only spread asyncConfig.typescript if you have TypeScript and typescript-eslint installed.

gotcha TypeScript users must apply a tseslint config (e.g., tseslint.configs.base) before asyncConfig.typescript. ↓

fix Include tseslint.configs.base in the config array before asyncConfig.typescript.

Install

npm install eslint-config-async

yarn add eslint-config-async

pnpm add eslint-config-async

Imports

base

wrong

module.exports = { extends: ['async'] }

correct

const asyncConfig = require('eslint-config-async'); module.exports = [ ...asyncConfig.base ];

v3 uses flat config only; array spread required. For ESM, use import asyncConfig from 'eslint-config-async'.

node

wrong

module.exports = { extends: ['async/node'] }

correct

const asyncConfig = require('eslint-config-async'); module.exports = [ ...asyncConfig.node ];

Node-specific rules are recommended for server-side code.

typescript

wrong

module.exports = { extends: ['async/typescript'] }

correct

const asyncConfig = require('eslint-config-async'); module.exports = [ ...asyncConfig.typescript ];

Requires typescript-eslint config to be applied first (e.g., tseslint.configs.base).

Quickstart

Sets up ESLint with async base and Node rules using flat config. Assumes ESLint v9 is installed.

// eslint.config.js
const asyncConfig = require('eslint-config-async');

module.exports = [
  ...asyncConfig.base,
  ...asyncConfig.node,
  {
    rules: {
      'no-console': 'warn',
    },
  },
];