How to Fix ESLint parserOptions.project Error

When you're using ESLint with TypeScript, you might encounter a frustrating parsing error that stops your linter from working on certain files. The error message points to parserOptions.project and tells you that a file wasn't found in any of the provided TypeScript projects. The fix is straightforward once you understand what's happening.

Contents

• The Error Message
• TypeScript Projects
• Understanding parserOptions.project
• The Solution
• Alternative

The Error Message

If you're seeing this error in your editor or terminal, it means ESLint's TypeScript parser package is trying to lint a file that TypeScript doesn't know about:

Parsing error: "parserOptions.project" has been provided for @typescript-eslint/parser. The file was not found in any of the provided project(s): tsdown.config.ts

This error appears when you configure ESLint to use TypeScript's project information for type-aware linting rules. The parser needs to know which files are part of your TypeScript project, but it can only check files that are included in your tsconfig.json.

TypeScript Projects

In TypeScript, a project is defined by a tsconfig.json file. This file describes which files belong to the project (include, exclude, files), how the compiler should analyze them (all compiler options) and how the output should be emitted (module system, target, paths, declaration settings, etc.).

The --project (or the shorthand -p) flag points to the config file that defines the project:

tsc --project tsconfig.production.json

Understanding parserOptions.project

Your ESLint configuration likely includes a parserOptions section that points to your TypeScript configuration:

module.exports = {
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaFeatures: {
      jsx: true,
    },
    // https://typescript-eslint.io/blog/parser-options-project-true/
    project: true,
  },
};

The project field tells ESLint which TypeScript configuration to use. When ESLint tries to lint a file, it checks whether that file is included in the TypeScript project. If the file isn't listed in the include array of your tsconfig.json, you get the parsing error.

The Solution

Instead of modifying your tsconfig.json to include configuration files that shouldn't be part of your build process, you can tell ESLint to ignore them. The cleanest approach is to add these files to the ignores array in your ESLint configuration.

Here's the fix that resolved the error for tsdown.config.ts:

import { defineConfig } from 'eslint/config';
import eslintConfig from '@tstv/eslint-config';
 
export default defineConfig({
  extends: [eslintConfig],
  files: ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}'],
  ignores: [
    '**/coverage/**',
    '**/dist/**',
    '**/docs/**',
    '**/tsdown.config.ts',
    '**/vitest.config.ts',
    'eslint.config.mjs',
  ],
});

By adding **/tsdown.config.ts to the ignores array, ESLint will skip linting this file entirely. This makes sense because configuration files often use patterns or features that don't need the same level of scrutiny as your application code.

Alternative

If you actually want ESLint to lint your configuration files with full type checking, you need to add them to your tsconfig.json instead:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "nodenext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*", "tsdown.config.ts", "vitest.config.ts"]
}

This approach makes sense if your configuration files contain complex logic that would benefit from type-aware linting rules.

Warning: Including config files in the tsconfig.json can lead to problems when specifying the rootDir compiler option. For example, you might encounter error "TS6059":

File '/tsdown.config.ts' is not under 'rootDir'. 'rootDir' is expected to contain all source files.

This happens because TypeScript expects all included files to be under the specified rootDir, which is typically set to your source directory.

Additionally, included config files will become part of the emitted JavaScript output, which is often unnecessary since these files are only needed during development and build time. For most projects, using ESLint's ignores array is the cleaner solution.