How to Fix "parserOptions.project" Errors in ESLint with TypeScript

By the end of this page, you will understand why ESLint sometimes throws a parserOptions.project error in TypeScript projects, especially for files like babel.config.js that are not part of tsconfig.json. You will learn what typed linting is, why ESLint checks TypeScript project boundaries, and the common ways to fix the problem in real projects.

When ESLint uses @typescript-eslint/parser with type-aware linting, it does more than read syntax. It also loads your TypeScript project configuration from tsconfig.json so it can understand types.

That is what parserOptions.project is about.

If ESLint is told to use a TypeScript project, then every file being linted must belong to that project. A file such as babel.config.js is usually a plain JavaScript config file, and it is often not included in tsconfig.json. When ESLint tries to lint it using the TypeScript parser in project mode, it fails because TypeScript does not consider that file part of the project.

This usually happens indirectly. In your config, airbnb-typescript-prettier commonly brings in settings that expect TypeScript project information. So even if you did not explicitly write parserOptions.project, the extended config may effectively require it.

Why this matters:

• Type-aware linting enables more powerful rules.
• But it also requires correct project boundaries.
• Mixed codebases often contain:
  • TypeScript source files
  • JavaScript config files
  • build scripts
  • test setup files
• These files should not always be linted the same way.

The fix is usually one of these:

• Ignore config files that should not be linted with the TypeScript project.
• Use ESLint overrides so .js config files use the default parser or a non-type-aware setup.

Think of tsconfig.json as a guest list for a private event.

• TypeScript files included in tsconfig.json are on the list.
• ESLint with parserOptions.project asks TypeScript to verify each guest.
• babel.config.js arrives at the door.
• TypeScript checks the guest list and says: "This file is not invited."
• ESLint then shows the parsing error.

So the problem is not that babel.config.js is invalid JavaScript. The problem is that ESLint is asking TypeScript to treat it like a file from the TypeScript project, but it is not on the project's list.

A common TypeScript ESLint setup looks like this:

module.exports = {
  parser: "@typescript-eslint/parser",
  parserOptions: {
    project: "./tsconfig.json"
  },
  plugins: ["@typescript-eslint"],
  extends: [
    "plugin:@typescript-eslint/recommended",
    "plugin:@typescript-eslint/recommended-requiring-type-checking"
  ]
};

This enables rules that require TypeScript type information.

If ESLint also tries to lint babel.config.js, you may get an error because that file is not included in tsconfig.json.

Option 1: Ignore config files

module.exports = {
  parser: "@typescript-eslint/parser",
  parserOptions: {
    project: "./tsconfig.json"
  },
  plugins: ["@typescript-eslint"],
  extends: ["airbnb-typescript-prettier"],
  ignorePatterns: ["babel.config.js", "metro.config.js"]
};

Use this when you do not need ESLint to check those files.

Consider this ESLint config:

module.exports = {
  parser: "@typescript-eslint/parser",
  parserOptions: {
    project: "./tsconfig.json"
  }
};

And assume tsconfig.json includes only TypeScript source files:

{
  "include": ["src/**/*", "App.tsx"]
}

Now ESLint opens babel.config.js.

What happens step by step

1. ESLint starts linting babel.config.js.
2. It sees that the parser is @typescript-eslint/parser.
3. Because parserOptions.project is set, the parser loads tsconfig.json.
4. TypeScript checks whether babel.config.js is part of the project.
5. It is not listed in include, and it is not a TypeScript source file in the project.

This issue appears often in projects that mix TypeScript application code with JavaScript tooling files.

Common examples:

• React Native apps with babel.config.js and metro.config.js
• React apps with vite.config.js or webpack.config.js
• Node.js projects with jest.config.js or eslint.config.js
• Monorepos with multiple tsconfig.json files
• Build scripts stored in scripts/*.js

Typical situations:

• You want strict TypeScript linting for src/**/*.ts and src/**/*.tsx.
• You still want ESLint on config files.
• But those config files should not require TypeScript project type information.

This separation is very normal in production codebases. Most real projects do not treat all files the same.

In real projects, developers usually handle this with one of a few patterns.

Pattern 1: Type-aware linting only for TypeScript files

This is the most common setup.

module.exports = {
  root: true,
  overrides: [
    {
      files: ["*.ts", "*.tsx"],
      parser: "@typescript-eslint/parser",
      parserOptions: {
        project: "./tsconfig.json"
      },
      extends: [
        "plugin:@typescript-eslint/recommended",
        "plugin:@typescript-eslint/recommended-requiring-type-checking"
      ]
    },
    {
      files: ["*.js"],
      extends: ["eslint:recommended"]
    }
  ]
};

Why teams use it:

• Clear separation between TS and JS files
• Faster linting
• Fewer parser errors

Pattern 2: Dedicated ESLint TypeScript config

Many teams create tsconfig.eslint.json so linting can include test files, scripts, or other files not used by the compiler.

{
  "extends": 
   
    
    
    
  

1. Using the TypeScript parser for every file

Broken example:

module.exports = {
  parser: "@typescript-eslint/parser",
  parserOptions: {
    project: "./tsconfig.json"
  }
};

Why it breaks:

• ESLint applies the TypeScript project parser to all files, including .js config files.

How to avoid it:

• Use overrides
• Or ignore non-TypeScript files

2. Assuming extends does not affect parser behavior

Many configs such as Airbnb TypeScript presets bring in rules that need type information.

How to avoid it:

• Read the preset documentation
• Check whether it requires parserOptions.project

3. Adding JavaScript files to tsconfig.json without understanding the effect

Possible fix, but not always ideal:

{
  "include": [ 

// Type-aware TypeScript ESLint setup
module.exports = {
  parser: "@typescript-eslint/parser",
  parserOptions: {
    project: "./tsconfig.json"
  }
};

Key rule

If parserOptions.project is used, every linted file must:

• be included in the referenced TypeScript config
• or be ignored
• or be handled by an override without project

Common fixes

// Ignore file
ignorePatterns: ["babel.config.js"]

// Disable project mode for specific files
overrides: [
  {
    files: ["*.js", "*.config.js"],
    parserOptions: {
      project: null
    }
  }
]

// Use a dedicated ESLint TS config
parserOptions: {
  project: "./tsconfig.eslint.json"
}

Why does ESLint complain about babel.config.js in a TypeScript project?

Because ESLint is using the TypeScript parser in project mode, and babel.config.js is usually not included in tsconfig.json.

What does parserOptions.project do?

It tells @typescript-eslint/parser to load a TypeScript project so ESLint can run rules that require type information.

Should I add babel.config.js to tsconfig.json?

Usually not. It is often better to ignore it, use an override, or create tsconfig.eslint.json.

What is the best fix for most projects?

Use overrides so TypeScript files use project-based linting and JavaScript config files do not.

Can I lint JavaScript and TypeScript files in the same project?

Yes. This is very common. You usually configure different parser options or rule sets for different file patterns.

Why did this start after extending an Airbnb TypeScript config?

Because TypeScript-focused shared configs often expect type-aware linting and may rely on parserOptions.project.

What is tsconfig.eslint.json used for?

• tsconfig.json — Defines which files belong to a TypeScript project.
• ESLint overrides — Lets you apply different linting rules to different file types.
• @typescript-eslint/parser — Parses TypeScript for ESLint.
• Type-aware linting — Enables ESLint rules that use TypeScript's type system.
• Ignore patterns — Excludes files and folders from linting.
• Shared ESLint configs — Presets like Airbnb can add parser and rule expectations.
• React Native configuration files — Files like babel.config.js and metro.config.js often need separate lint handling.
• JavaScript vs TypeScript tooling files — Mixed codebases often need different lint strategies for each.