The Ultimate 2025 Guide to ESLint Generics in Monorepos

First, ensure your monorepo uses TypeScript's Project References. This is the canonical way to link packages within a TypeScript monorepo.

Your root tsconfig.json might look like this, simply referencing the packages in your workspace:

// ./tsconfig.json
{
  "files": [],
  "references": [
    { "path": "./packages/utils" },
    { "path": "./packages/ui" },
    { "path": "./packages/api" }
  ]
}

And a package that depends on another, like @my-app/ui depending on @my-app/utils:

// ./packages/ui/tsconfig.json
{
  "extends": "../../tsconfig.base.json", // A base config with compilerOptions
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "references": [
    { "path": "../utils" }
  ]
}

Centralized vs. Package-Level ESLint Configs

You have two main approaches for your ESLint configuration, but the hybrid model is often the most effective.

In the hybrid model, you'd have a .eslintrc.js in the root defining all your rules, plugins, and parsers, but without the parserOptions.project setting. Then, in each package, you create a tiny .eslintrc.js that extends the root config and adds the project path.

// ./packages/ui/.eslintrc.js
module.exports = {
  extends: ['../../.eslintrc.js'], // Extend the root config
  parserOptions: {
    // Point to the tsconfig for this specific package
    project: './tsconfig.json',
    tsconfigRootDir: __dirname, // Important for resolving paths correctly
  },
};

Leveraging typescript-eslint's project Setting

The parserOptions.project property is your most important tool. As of 2025, the best practice is to create a dedicated tsconfig.eslint.json file. This file extends your main tsconfig.json but includes all files you want to lint, including configuration files and test files, which you might normally exclude from a production build.

// ./packages/ui/tsconfig.eslint.json
{
  // Inherit all the settings from the main tsconfig
  "extends": "./tsconfig.json",
  // Include all files that ESLint should be aware of
  "include": ["src/**/*.ts", "src/**/*.tsx", "tests/**/*.ts", "../utils/src/**/*.ts"]
}

Then, your package-level .eslintrc.js points to this new file:

// ./packages/ui/.eslintrc.js
module.exports = {
  extends: ['../../.eslintrc.js'],
  parserOptions: {
    project: './tsconfig.eslint.json', // Point to the dedicated ESLint tsconfig
    tsconfigRootDir: __dirname,
  },
};

This approach gives ESLint's parser the complete context it needs to trace your generic types back to their source in another package, finally resolving those frustrating errors.

Solving Common Generic-Related ESLint Errors

Let's tackle some common error messages and their solutions within this new structure.

Error: Parsing error: "parserOptions.project" has been set for @typescript-eslint/parser. The file does not match your project config.

Cause: The file you are linting is not included in the include array of the tsconfig.json file you specified in parserOptions.project.

Solution: This is exactly why tsconfig.eslint.json is a best practice. Ensure its include pattern is broad enough to cover all relevant files. For example, "include": ["src/**/*.ts", "tests/**/*.ts", ".eslintrc.js"].

Error: Unable to resolve path to module '@my-app/utils'. (import/no-unresolved)

Cause: This is from eslint-plugin-import. It doesn't know how to resolve your monorepo's internal package aliases (like @my-app/utils).

Solution: You need to give the import plugin a helping hand. Install eslint-import-resolver-typescript and configure it in your root .eslintrc.js.

// ./.eslintrc.js
module.exports = {
  // ... other settings
  settings: {
    'import/resolver': {
      typescript: {
        project: 'packages/*/tsconfig.json',
      },
    },
  },
};

Advanced Patterns & Best Practices

Using eslint-import-resolver-typescript

As shown above, this resolver is non-negotiable in a TypeScript monorepo. It reads your tsconfig.json files (including the paths and references) to teach ESLint's import plugin how your workspace is structured. The glob pattern packages/*/tsconfig.json is powerful, as it automatically discovers all your packages.

Conditional ESLint Overrides

Your monorepo might contain different types of packages (e.g., React, Node.js, tests). Use ESLint's overrides key in your root config to apply different rules or settings to different subsets of files.

// ./.eslintrc.js
module.exports = {
  // ... base config
  overrides: [
    // Apply React-specific rules only to the 'ui' package
    {
      files: ['packages/ui/**/*'],
      extends: [
        'plugin:react/recommended',
        'plugin:react-hooks/recommended',
      ],
    },
    // Apply Jest rules only to test files
    {
      files: ['**/__tests__/**/*', '**/*.test.ts'],
      extends: ['plugin:jest/recommended'],
    },
  ],
};

Performance Tuning in Large Monorepos

Linting an entire monorepo with type-aware rules can be slow. Here are two tips for 2025:

1. Use the Cache: Always run ESLint with the --cache flag (e.g., eslint . --cache). This creates a cache file and only lints files that have changed, drastically speeding up subsequent runs.
2. Scoped Linting: Use your monorepo tooling (like Nx, Turborepo, or Lerna) to only lint affected packages. For example, npx turbo run lint will intelligently run the lint script only in packages that have changed since the last commit.

The Future: What's Next for ESLint and TypeScript?

The collaboration between the ESLint and TypeScript teams is stronger than ever. We can expect continued performance improvements in @typescript-eslint, especially for large, type-heavy projects. There's also ongoing work to make the configuration less complex, potentially with better auto-detection of monorepo structures in the future. Tools like Rome and Biome are also emerging as all-in-one formatters/linters, but for now, ESLint remains the undisputed king of customizability and power in the JavaScript ecosystem.

Conclusion: Taming the Beast for Good

The friction between ESLint, TypeScript generics, and monorepos stems from a context problem: ESLint's single-file view clashing with the project-wide nature of types. By adopting a modern setup—leveraging TypeScript Project References and a hybrid ESLint config with dedicated tsconfig.eslint.json files—you provide ESLint with the full picture it needs to work its magic.

It requires some initial setup, but the payoff is immense: a stable, reliable linting system that catches real bugs, enforces consistency, and lets you harness the full power of TypeScript generics without the headache. Now you can get back to what matters most: building amazing software.