ESLint Parsing Error: TSConfig File Inclusion

TL;DR

ESLint throws the TSConfig does not include this file error when files processed by TypeScript ESLint aren't covered by your tsconfig.json's include patterns. The main fixes are:

1. Set tsconfigRootDir: __dirname in ESLint config
2. Adjust include/exclude in tsconfig.json
3. Use ignorePatterns to exclude non-project files
4. Create separate TSConfig for test files

Problem Statement

When using ESLint with TypeScript and Cypress in projects like Remix, you may encounter this error:

Parsing error: ESLint was configured to run on `<tsconfigRootDir>/component/TestComponent.cy.ts` using `parserOptions.project`: <tsconfigRootDir>/../../../../../../users/tduke/desktop/dev/blog/cypress/tsconfig.json
However, that TSConfig does not include this file. Either:
- Change ESLint's list of included files to not include this file
- Change that TSConfig to include this file
- Create a new TSConfig that includes this file and include it in your parserOptions.project

This occurs because:

1. ESLint's TypeScript parser requires files to be included in your tsconfig.json
2. Cypress test files are often in different locations than application code
3. Configuration files like .eslintrc.js might not be included
4. tsconfigRootDir might not be properly set for relative paths

Solutions

1. Configure ESLint Properly

Update .eslintrc.js with correct tsconfigRootDir:

module.exports = {
  // ... existing config ...
  root: true, // Ensure ESLint recognizes root config
  parserOptions: {
    project: './tsconfig.json',
    tsconfigRootDir: __dirname, // 👈 Critical for path resolution
  },
  ignorePatterns: [
    '.eslintrc.js',     // Exclude config files
    'cypress.config.ts',
    'jest.config.*',
    'vite.config.ts',   // Add other config files
    'dist/**/*',        // Ignore build outputs
    'generated/**/*'    // Ignore generated files
  ],  
};

2. Adjust TSConfig Inclusion

Ensure tsconfig.json covers all necessary files:

{
  "include": [
    "remix.env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    "**/*.js",
    "**/*.jsx",
    "cypress/**/*.cy.ts", // Include Cypress tests
    "component/**/*.cy.ts" // Custom file locations
  ],
  "exclude": [
    "node_modules",
    "dist",
    "cypress/e2e", // Separate config needed for e2e tests
    "*.config.js"   // Config files
  ],
  "compilerOptions": {
    // ... your existing options ...
  }
}

3. Create Specialized TSConfigs (Advanced)

For complex projects, create separate configurations:

{
  "extends": "./tsconfig.json",
  "include": [
    "**/*.ts",
    "**/*.tsx",
    "cypress/**/*.cy.ts",
    ".eslintrc.js" // Include ESLint config
  ]
}

{
  "extends": "./tsconfig.json",
  "include": ["cypress/**/*.cy.ts"]
}

Update ESLint to use the specialized config:

module.exports = {
  overrides: [
    {
      files: ['**/*.cy.ts'],
      parserOptions: {
        project: './tsconfig.cypress.json'
      }
    }
  ]
};

4. Handle Symlinks and Path Issues

If your project is accessed via symlinks:

# Resolve symlink issues:
pwd -P  # Shows real path
cd "$(pwd -P)"  # Switch to physical path

Explanation

Why These Solutions Work

1. tsconfigRootDir: __dirname
   Resolves path ambiguity by specifying where to start resolving the TSConfig path

2. Expanded include patterns
   Explicitly includes test files that exist outside normal source directories

3. ignorePatterns
   Prevents ESLint from trying to lint non-project files that TypeScript ignores

4. Specialized TSConfigs
   Provides type information for tests without polluting app TSConfig

Pitfalls to Avoid

• Don't forget to exclude node_modules in tsconfig.json
• Avoid mixing JavaScript and TypeScript files without explicit inclusion
• Don't include build artifacts in TSConfig (dist, build)
• Never remove project configuration entirely (loses type-aware linting)

When to Use Each Solution

Solution	Best For	Complexity
tsconfigRootDir setting	Basic setup fixes	⭐
TSConfig include adjustment	Simple project structures	⭐⭐
ignorePatterns	Excluding config files	⭐
Custom TSConfigs	Monorepos, complex project layouts	⭐⭐⭐

Pro Tip

Create .eslintignore for file exclusions rather than polluting ignorePatterns:

# .eslintignore
dist/
node_modules/
coverage/
*.config.*
cypress/fixtures/

Conclusion

The "TSConfig does not include this file" error stems from mismatches between ESLint's file processing and TypeScript's project configuration. By carefully configuring tsconfigRootDir, adjusting include/exclude paths, ignoring non-source files, or creating specialized TSConfigs, you maintain robust type-aware linting while supporting test files in isolated directories.