How to fix @typescript-eslint cannot parse file without TypeScript in TypeScript

TypeScriptINTERMEDIATEMEDIUM

This error occurs when ESLint is configured to use @typescript-eslint/parser with type-aware linting (parserOptions.project), but tries to lint a file that isn't included in your TypeScript configuration. Files must be in your tsconfig.json's include array or you need to adjust ESLint's configuration to exclude them.

What this error means

The "@typescript-eslint cannot parse file without TypeScript" error appears when ESLint attempts to apply type-aware linting rules to a file that isn't part of your TypeScript project. This happens because you've configured parserOptions.project in your ESLint config, which tells @typescript-eslint/parser to use TypeScript's type checker for enhanced linting rules. When parserOptions.project is set, ESLint needs to generate type information for each file using your tsconfig.json. If a file isn't included in that TypeScript configuration (or is explicitly excluded), the parser cannot build the type information and throws this error. This commonly occurs with configuration files (like .eslintrc.js, jest.config.js), build scripts, or files in directories that are intentionally excluded from TypeScript compilation. The error is actually a safety mechanism - it prevents ESLint from making incorrect type-based assumptions about files that TypeScript isn't supposed to process.

How to fix "@typescript-eslint cannot parse file without TypeScript"

1Add files to tsconfig.json include array

If the files should be type-checked, add them to your tsconfig.json:

json

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es2020"
  },
  "include": [
    "src/**/*",
    "*.js",              // Include root-level JS files
    "scripts/**/*.ts",   // Include scripts directory
    "test/**/*.ts"       // Include test files
  ]
}

For projects with config files at root:

json

{
  "include": [
    "src",
    ".eslintrc.js",
    "jest.config.js",
    "*.config.js"
  ]
}

After updating tsconfig.json, restart your IDE's TypeScript server.

2Create tsconfig.eslint.json for ESLint-specific files

Instead of modifying your main tsconfig.json, create a separate config for ESLint:

json

// tsconfig.eslint.json
{
  "extends": "./tsconfig.json",
  "include": [
    "src/**/*",
    "*.js",
    "*.config.js",
    ".eslintrc.js",
    "scripts/**/*",
    "test/**/*"
  ]
}

Then reference it in your ESLint config:

javascript

// .eslintrc.js
module.exports = {
  parser: "@typescript-eslint/parser",
  parserOptions: {
    project: "./tsconfig.eslint.json",
    tsconfigRootDir: __dirname,
  },
  // ... rest of config
};

This approach keeps your TypeScript compilation config separate from your linting config.

3Use ESLint overrides to disable type-aware rules for specific files

Configure ESLint to use different parser settings for JavaScript config files:

javascript

// .eslintrc.js
module.exports = {
  parser: "@typescript-eslint/parser",
  parserOptions: {
    project: "./tsconfig.json",
  },
  overrides: [
    {
      // Disable type-aware linting for JS files
      files: ["*.js", "*.config.js"],
      parserOptions: {
        project: null,  // Disable type checking
      },
      rules: {
        "@typescript-eslint/no-var-requires": "off",
      },
    },
    {
      // Different config for test files
      files: ["**/__tests__/**", "**/*.test.ts"],
      parserOptions: {
        project: "./tsconfig.test.json",
      },
    },
  ],
};

This tells ESLint not to apply type-aware linting to files that aren't TypeScript source code.

4Add files to .eslintignore

If files shouldn't be linted at all, add them to .eslintignore:

plaintext

# .eslintignore
node_modules/
dist/
build/
*.config.js
.eslintrc.js
coverage/
scripts/

Or use ignorePatterns in .eslintrc.js:

javascript

module.exports = {
  ignorePatterns: [
    "dist",
    "build",
    "*.config.js",
    ".eslintrc.js",
    "scripts/**/*",
  ],
  // ... rest of config
};

This completely skips ESLint processing for these files.

5Verify TypeScript is installed locally

Ensure TypeScript is installed as a local dependency, not globally:

bash

# Check if TypeScript is in package.json
cat package.json | grep typescript

# If not installed locally, add it
npm install --save-dev typescript

# Verify version
npx tsc --version

# For @typescript-eslint dependencies
npm install --save-dev @typescript-eslint/parser @typescript-eslint/eslint-plugin

Global TypeScript installations can cause resolution issues with ESLint.

6Use projectService for automatic tsconfig detection (recommended)

Modern @typescript-eslint/parser (v6+) supports projectService for simpler configuration:

javascript

// .eslintrc.js
module.exports = {
  parser: "@typescript-eslint/parser",
  parserOptions: {
    projectService: true,  // Automatically finds nearest tsconfig.json
    tsconfigRootDir: __dirname,
  },
  plugins: ["@typescript-eslint"],
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended-type-checked",
  ],
};

This automatically uses the nearest tsconfig.json for each file and is more forgiving with project structure.

For older versions, use project: true:

javascript

parserOptions: {
  project: true,
  tsconfigRootDir: __dirname,
}

Advanced notes

### Understanding parserOptions.project

The parserOptions.project setting enables type-aware linting rules like:
- @typescript-eslint/no-floating-promises
- @typescript-eslint/no-misused-promises
- @typescript-eslint/await-thenable
- @typescript-eslint/no-unnecessary-type-assertion

These rules require TypeScript's type checker to work. Setting project tells ESLint which tsconfig.json to use for type information. However, this comes with a cost: every file ESLint processes must be included in that TypeScript configuration.

Options for parserOptions.project:

javascript

// Single tsconfig
project: "./tsconfig.json"

// Multiple tsconfigs
project: ["./tsconfig.json", "./tsconfig.test.json"]

// Automatic detection (v6+)
project: true

// Automatic with projectService (v6.21.0+, recommended)
projectService: true

### Performance Considerations

Type-aware linting is significantly slower than basic linting because it requires building TypeScript's type graph. For large projects:

Option 1: Selective type-aware linting

javascript

module.exports = {
  extends: [
    "plugin:@typescript-eslint/recommended",  // Fast rules only
  ],
  overrides: [
    {
      files: ["src/**/*.ts"],
      extends: [
        "plugin:@typescript-eslint/recommended-type-checked",  // Slower, type-aware rules
      ],
      parserOptions: {
        project: "./tsconfig.json",
      },
    },
  ],
};

Option 2: Use allowDefaultProject (not recommended for production)

javascript

parserOptions: {
  project: "./tsconfig.json",
  allowDefaultProject: true,  // Allows linting files outside project
}

This creates a default project for orphaned files but may produce incorrect type information.

### Monorepo Setup

For monorepos with multiple packages:

javascript

// Root .eslintrc.js
module.exports = {
  parser: "@typescript-eslint/parser",
  parserOptions: {
    project: [
      "./tsconfig.json",
      "./packages/*/tsconfig.json",
    ],
    tsconfigRootDir: __dirname,
  },
};

Or use projectService for automatic detection:

javascript

parserOptions: {
  projectService: {
    allowDefaultProject: ["*.js"],
    defaultProject: "./tsconfig.json",
  },
  tsconfigRootDir: __dirname,
}

### Debugging Configuration Issues

Check which files are included in your TypeScript project:

bash

# List all files TypeScript sees
npx tsc --listFiles | grep -v node_modules

# Show detailed resolution
npx tsc --explainFiles

Enable ESLint debug output:

bash

DEBUG=eslint:* npx eslint src/

Check @typescript-eslint parser version compatibility:

bash

npm list @typescript-eslint/parser @typescript-eslint/eslint-plugin typescript

Ensure all three versions are compatible (same major version for parser and plugin).

### Common Gotchas

1. Case sensitivity in include patterns:

json

// Won't match *.JS files on Linux
"include": ["src/**/*.js"]

// Better: be explicit
"include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.js", "src/**/*.jsx"]

2. Exclude takes precedence over include:

json

{
  "include": ["src"],
  "exclude": ["src/scripts"]  // src/scripts won't be included
}

3. Files outside project root:

If files are symlinked or outside your project root, use absolute paths or set tsconfigRootDir properly.

How to fix @typescript-eslint cannot parse file without TypeScript in TypeScript

What this error means

Typical symptoms

Common causes

How to fix "@typescript-eslint cannot parse file without TypeScript"

Advanced notes

Related errors

Official resources & further reading