@typescript-eslint/parser 8.x

Complete instructions

Verified against @typescript-eslint/parser@8.70.0 on 2026-09-08. 3 of 3 examples executed.

@typescript-eslint/parser v8

@typescript-eslint/parser parses TypeScript into ESLint-compatible nodes and can provide backing TypeScript programs. It is an ESLint parser, not a compiler or standalone lint runner. Its direct API is useful for parsing and inspecting ASTs; lint rules and ESLint configuration are exercised by ESLint itself.

Direct parsing

Import the package by name and call parse with TypeScript source. The result is an ESLint-compatible AST. filePath is a parser option and is useful when parser behavior depends on the apparent file name.

import * as assert from 'node:assert/strict';
import * as parser from '@typescript-eslint/parser';

const ast = parser.parse('let x: number = 1;', {
  filePath: 'example.ts',
});

assert.equal(ast.type, 'Program');
assert.equal(ast.body.length, 1);
assert.equal(ast.body[0].type, 'VariableDeclaration');
assert.equal(ast.body[0].declarations[0].id.type, 'Identifier');
assert.equal(ast.body[0].declarations[0].id.typeAnnotation.type, 'TSTypeAnnotation');

parse accepts either source text or a TypeScript SourceFile. For ordinary standalone parsing, pass source text and parser options.

parseForESLint

Use parseForESLint when the consumer needs the complete parser result rather than only the AST. The result contains ast, services, visitorKeys, and scopeManager.

import * as assert from 'node:assert/strict';
import * as parser from '@typescript-eslint/parser';

const result = parser.parseForESLint('const answer: number = 42;', {
  filePath: 'example.ts',
});

assert.equal(result.ast.type, 'Program');
assert.ok(result.services);
assert.ok(result.visitorKeys);
assert.ok(result.scopeManager);
assert.equal(result.ast.body[0].type, 'VariableDeclaration');

The parser can expose TypeScript-backed services when configured for type-aware parsing. Type-aware parsing requires projectService or project; if programs is supplied, it must contain every file being linted. A direct script should not assume that type information exists merely because the input is TypeScript.

Isolated parsing with withoutProjectParserOptions

withoutProjectParserOptions removes project-based parser settings so parsing can be performed without a TypeScript project. Use it when a caller may provide type-aware options but this parse must remain isolated. Do not assume that unrelated options, such as tsconfigRootDir, are removed.

import * as assert from 'node:assert/strict';
import * as parser from '@typescript-eslint/parser';

const isolated = parser.withoutProjectParserOptions({
  filePath: 'example.ts',
  project: './tsconfig.json',
  projectService: true,
  tsconfigRootDir: '/tmp/project',
});

assert.equal(isolated.project, undefined);
assert.equal(isolated.projectService, undefined);
assert.equal(isolated.filePath, 'example.ts');
assert.equal(isolated.tsconfigRootDir, '/tmp/project');

const result = parser.parseForESLint('const value: string = "ok";', isolated);
assert.equal(result.ast.type, 'Program');

This is particularly important for direct invocation: type-aware options are not self-contained, and project-backed parsing needs the relevant project configuration or supplied programs.

Project-backed parsing

createProgram(configFile, projectDirectory?) creates a TypeScript Program from a configuration file. The resulting program can be supplied through parser options where appropriate. This operation requires a real tsconfig.json and project files, so it is normally used by an ESLint or tooling process rather than a self-contained script. A standalone example cannot create those files under the execution constraints for this skill.

The parser also supports documented options including project, programs, projectService, tsconfigRootDir, lib, ecmaVersion, ecmaFeatures, jsxPragma, jsxFragmentName, extraFileExtensions, jsDocParsingMode, and controls for unsupported TypeScript versions.

v8 configuration mistake: Project Service spelling

In v8, use:

parserOptions: { projectService: true }

The older experimental spelling is:

parserOptions: { EXPERIMENTAL_useProjectService: true }

Do not copy the older experimental name into new v8 configuration. project remains supported, while projectService is the stable v8 Project Service option. Project Service automatically uses the nearest tsconfig.json, can type-check JavaScript without allowJs, and is an alternative to project.

ESLint integration

This package supplies the parser; it does not define describe, it, or expect, and it does not run lint rules. The rest of the workflow is run by ESLint.

The older legacy ESLint shape still commonly appears as:

module.exports = {
  extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
  parser: '@typescript-eslint/parser',
  plugins: ['@typescript-eslint'],
  root: true,
};

The parser entry is required in that setup; otherwise ESLint parses TypeScript as JavaScript and errors. With flat config, the parser is configured under languageOptions; a typical v8-era shape is:

export default [{
  languageOptions: {
    parserOptions: { projectService: true },
  },
}];

As of v7/v8, the recommended package is generally typescript-eslint; flat-config users usually do not need to install @typescript-eslint/parser explicitly when using that package.

Other exports

The v8 entry point also exports clearCaches, version, and meta, along with parser-related types. clearCaches is for clearing parser caches in a long-lived tooling process. version and meta provide package/parser metadata. TypeScript types such as ParserOptions, ParserServices, ParserServicesWithTypeInformation, and ParserServicesWithoutTypeInformation are useful to TypeScript consumers but do not produce runtime values.

Does not cover

• ESLint rule execution, CLI invocation, or complete ESLint configuration.
• The contents or layout of a real tsconfig.json project.
• Which files a particular TypeScript program includes.
• Detailed AST node schemas beyond the directly demonstrated fields.
• TypeScript compiler behavior or type-checking semantics.
• Performance tuning, cache internals, or the full behavior of every parser option.
• A standalone createProgram example, because it requires project files that are unavailable to the self-contained example runner.