Skip to main content

@typescript-eslint/parser

An ESLint parser used to parse TypeScript code into ESLint-compatible nodes, as well as provide backing TypeScript programs. ✨

This is necessary because TypeScript produces a different, incompatible AST format to the one that ESLint requires to work. For example, this is not valid JavaScript code because it contains the : number type annotation:

let x: number = 1;

ESLint's native Espree parser would raise an error attempting to parse it.

Additionally, because TypeScript is developed separately and with different goals from ESLint, ESTree, and Espree, its AST also represents nodes differently in many cases. TS's AST is optimized for its use case of parsing incomplete code and typechecking. ESTree is unoptimized and intended for "general purpose" use-cases of traversing the AST.

tip

You can select @typescript-eslint/parser on the typescript-eslint playground's right sidebar by selecting ESTree.

Configuration​

The following additional configuration options are available by specifying them in parserOptions in your ESLint configuration file.

interface ParserOptions {
  allowAutomaticSingleRunInference?: boolean;
  cacheLifetime?: {
    glob?: number | 'Infinity';
  };
  ecmaFeatures?: {
    jsx?: boolean;
    globalReturn?: boolean;
  };
  ecmaVersion?: number | 'latest';
  emitDecoratorMetadata?: boolean;
  experimentalDecorators?: boolean;
  extraFileExtensions?: string[];
  jsDocParsingMode?: 'all' | 'none' | 'type-info';
  jsxFragmentName?: string | null;
  jsxPragma?: string | null;
  lib?: string[];
  programs?: import('typescript').Program[];
  project?: string | string[] | boolean | null;
  projectFolderIgnoreList?: string[];
  tsconfigRootDir?: string;
  warnOnUnsupportedTypeScriptVersion?: boolean;
  EXPERIMENTAL_useProjectService?: boolean;
}

allowAutomaticSingleRunInference​

Default process.env.TSESTREE_SINGLE_RUN or false.

Whether to use common heuristics to infer whether ESLint is being used as part of a single run (as opposed to --fix mode or in a persistent session such as an editor extension).

When typescript-eslint handles TypeScript Program management behind the scenes for linting with type information, this distinction is important for performance. There is significant overhead to managing TypeScript "Watch" Programs needed for the long-running use-case. Being able to assume the single run case allows typescript-eslint to faster immutable Programs instead.

This setting's default value can be specified by setting a TSESTREE_SINGLE_RUN environment variable to "false" or "true". For example, TSESTREE_SINGLE_RUN=true npx eslint . will enable it.

tip

We've seen allowAutomaticSingleRunInference improve linting speed in CI by up to 10-20%. Our plan is to enable allowAutomaticSingleRunInference by default in an upcoming major version.

cacheLifetime​

This option allows you to granularly control our internal cache expiry lengths.

You can specify the number of seconds as an integer number, or the string 'Infinity' if you never want the cache to expire.

By default cache entries will be evicted after 30 seconds, or will persist indefinitely if the parser infers that it is a single run (see allowAutomaticSingleRunInference).

ecmaFeatures​

Optional additional options to describe how to parse the raw syntax.

jsx​

Default false.

Enable parsing JSX when true. More details can be found in the TypeScript handbook's JSX docs.

NOTE: this setting does not affect known file types (.js, .mjs, .cjs, .jsx, .ts, .mts, .cts, .tsx, .json) because the TypeScript compiler has its own internal handling for known file extensions.

The exact behavior is as follows:

  • .js, .mjs, .cjs, .jsx, .tsx files are always parsed as if this is true.
  • .ts, .mts, .cts files are always parsed as if this is false.
  • For "unknown" extensions (.md, .vue):
    • If parserOptions.project is not provided:
      • The setting will be respected.
    • If parserOptions.project is provided (i.e. you are using rules with type information):
      • always parsed as if this is false

globalReturn​

Default false.

This options allows you to tell the parser if you want to allow global return statements in your codebase.

ecmaVersion​

Default 2018.

Accepts any valid ECMAScript version number or 'latest':

  • A version: es3, es5, es6, es7, es8, es9, es10, es11, es12, es13, ..., or
  • A year: es2015, es2016, es2017, es2018, es2019, es2020, es2021, es2022, ..., or
  • 'latest'

When it's a version or a year, the value must be a number - so do not include the es prefix.

Specifies the version of ECMAScript syntax you want to use. This is used by the parser to determine how to perform scope analysis, and it affects the default

emitDecoratorMetadata​

Default undefined.

This option allow you to tell parser to act as if emitDecoratorMetadata: true is set in tsconfig.json, but without type-aware linting. In other words, you don't have to specify parserOptions.project in this case, making the linting process faster.

experimentalDecorators​

Default undefined.

This option allow you to tell parser to act as if experimentalDecorators: true is set in tsconfig.json, but without type-aware linting. In other words, you don't have to specify parserOptions.project in this case, making the linting process faster.

extraFileExtensions​

Default undefined.

This option allows you to provide one or more additional file extensions which should be considered in the TypeScript Program compilation. The default extensions are ['.js', '.mjs', '.cjs', '.jsx', '.ts', '.mts', '.cts', '.tsx']. Add extensions starting with ., followed by the file extension. E.g. for a .vue file use "extraFileExtensions": [".vue"].

jsDocParsingMode​

Default if parserOptions.project is set, then 'all', otherwise 'none'

When TS parses a file it will also parse JSDoc comments into the AST - which can then be consumed by lint rules. If you are using TypeScript version >=5.3 then this option can be used as a performance optimization.

The valid values for this rule are:

  • 'all' - parse all JSDoc comments, always.
  • 'none' - parse no JSDoc comments, ever.
  • 'type-info' - parse just JSDoc comments that are required to provide correct type-info. TS will always parse JSDoc in non-TS files, but never in TS files.

If you do not use lint rules like eslint-plugin-deprecation that rely on TS's JSDoc tag representation, then you can set this to 'none' to improve parser performance.

jsxFragmentName​

Default null

The identifier that's used for JSX fragment elements (after transpilation). If null, assumes transpilation will always use a member of the configured jsxPragma. This should not be a member expression - just the root identifier (i.e. use "h" instead of "h.Fragment").

If you provide parserOptions.project, you do not need to set this, as it will automatically detected from the compiler.

jsxPragma​

Default 'React'

The identifier that's used for JSX Elements creation (after transpilation). If you're using a library other than React (like preact), then you should change this value. If you are using the new JSX transform you can set this to null.

This should not be a member expression - just the root identifier (i.e. use "React" instead of "React.createElement").

If you provide parserOptions.project, you do not need to set this, as it will automatically detected from the compiler.

lib​

Default ['es2018']

For valid options, see the TypeScript compiler options.

Specifies the TypeScript libs that are available. This is used by the scope analyser to ensure there are global variables declared for the types exposed by TypeScript.

If you provide parserOptions.project, you do not need to set this, as it will automatically detected from the compiler.

programs​

Default undefined.

This option allows you to programmatically provide an instance of a TypeScript Program object that will provide type information to rules. This will override any programs that would have been computed from parserOptions.project. All linted files must be part of the provided program(s).

Refer to the TypeScript Wiki for an example on how to write the resolveModuleNames function.

project​

Default undefined.

This option allows you to provide a path to your project's tsconfig.json. This setting is required if you want to use rules which require type information. Relative paths are interpreted relative to the current working directory if tsconfigRootDir is not set. If you intend on running ESLint from directories other than the project root, you should consider using tsconfigRootDir.

  • Accepted values:

    // find the tsconfig.json nearest each source file
    project: true,

    // path
    project: './tsconfig.json';

    // glob pattern
    project: './packages/**/tsconfig.json';

    // array of paths and/or glob patterns
    project: ['./packages/**/tsconfig.json', './separate-package/tsconfig.json'];

    // ways to disable type-aware linting (useful for overrides configs)
    project: false;
    project: null;

  • If true, each source file's parse will find the nearest tsconfig.json file to that source file.

    • This is done by checking that source file's directory tree for the nearest tsconfig.json.

  • If you use project references, TypeScript will not automatically use project references to resolve files. This means that you will have to add each referenced tsconfig to the project field either separately, or via a glob.

  • Note that using wide globs ** in your parserOptions.project may cause performance implications. Instead of globs that use ** to recursively check all folders, prefer paths that use a single * at a time. For more info see #2611.

  • TypeScript will ignore files with duplicate filenames in the same folder (for example, src/file.ts and src/file.js). TypeScript purposely ignore all but one of the files, only keeping the one file with the highest priority extension (the extension priority order (from highest to lowest) is .ts, .tsx, .d.ts, .js, .jsx). For more info see #955.

  • Note that if this setting is specified, you must only lint files that are included in the projects as defined by the provided tsconfig.json files. If your existing configuration does not include all of the files you would like to lint, you can create a separate tsconfig.eslint.json as follows:

    {
      // extend your base config so you don't have to redefine your compilerOptions
      "extends": "./tsconfig.json",
      "include": [
        "src/**/*.ts",
        "test/**/*.ts",
        "typings/**/*.ts",
        // etc

        // if you have a mixed JS/TS codebase, don't forget to include your JS files
        "src/**/*.js",
      ],
    }

projectFolderIgnoreList​

Default ["**/node_modules/**"].

This option allows you to ignore folders from being included in your provided list of projects. This is useful if you have configured glob patterns, but want to make sure you ignore certain folders.

It accepts an array of globs to exclude from the project globs.

For example, by default it will ensure that a glob like ./**/tsconfig.json will not match any tsconfigs within your node_modules folder (some npm packages do not exclude their source files from their published packages).

tsconfigRootDir​

Default undefined.

This option allows you to provide the root directory for relative TSConfig paths specified in the project option above. Doing so ensures running ESLint from a directory other than the root will still be able to find your TSConfig.

warnOnUnsupportedTypeScriptVersion​

Default true.

This option allows you to toggle the warning that the parser will give you if you use a version of TypeScript which is not explicitly supported. The warning message would look like this:

=============

WARNING: You are currently running a version of TypeScript which is not officially supported by @typescript-eslint/typescript-estree.

You may find that it works just fine, or you may not.

SUPPORTED TYPESCRIPT VERSIONS: >=3.3.1 <5.1.0

YOUR TYPESCRIPT VERSION: 5.1.3

Please only submit bug reports when using the officially supported version.

=============

EXPERIMENTAL_useProjectService​

Default false.

An experimental alternative to parserOptions.project. This directs the parser to use a more seamless TypeScript API to generate type information for rules. It will automatically detect the TSConfig for each file (like project: true), and will also allow type information to be computed for JavaScript files without the allowJs compiler option (unlike project: true).

module.exports = {
  parser: '@typescript-eslint/parser',
  parserOptions: {
    EXPERIMENTAL_useProjectService: true,
  },
};

This option should bring two main benefits:

  • Simpler configurations: most projects shouldn't need to explicitly configure project paths or create tsconfig.eslint.jsons
  • Improved performance: this API is optimized on the TypeScript side for speed
    • Initial versions of this option demonstrated performance changes in subsets of the typescript-eslint monorepo ranging from 11% slower to 70% faster

We're hopeful this option will eventually become the standard way to enable typed linting. It switches the parser from manually creating TypeScript programs to instead calling the same "project services" API used by editors such as VS Code. However, because it's so new and untested, we're keeping it under the EXPERIMENTAL_ prefix for at least all of the 6.X versions.

See feat(typescript-estree): add EXPERIMENTAL_useProjectService option to use TypeScript project service for more information.

Utilities​

createProgram(configFile, projectDirectory)​

This serves as a utility method for users of the parserOptions.programs feature to create a TypeScript program instance from a config file.

declare function createProgram(
  configFile: string,
  projectDirectory?: string,
): import('typescript').Program;

Example usage:

.eslintrc.js
const parser = require('@typescript-eslint/parser');

module.exports = {
  parserOptions: {
    programs: [parser.createProgram('tsconfig.json')],
  },
};