Dec 6, 2023 · Dec 24, 2023 · Dec 24, 2023 · Dec 24, 2023 · Dec 27, 2023 · May 11, 2024
diff --git a/.cspell.json b/.cspell.json
    "tsconfigrootdir",
    "tsconfigs",
    "tseslint",
    "tsgo",
    "tsvfs",
    "typedef",
    "typedefs",
diff --git a/docs/packages/Parser.mdx b/docs/packages/Parser.mdx
 It will automatically use the nearest `tsconfig.json` for each file (like `project: true`).
 It can also be configured to also allow type information to be computed for JavaScript files without the `allowJs` compiler option (unlike `project: true`).

 See [Typed Linting with `parserOptions.projectService`](/blog/project-service) for more context.

 <Tabs groupId="eslint-config">
 <TabItem value="Flat Config">

diff --git a/docs/packages/Project_Service.mdx b/docs/packages/Project_Service.mdx
 These APIs are what editors such as VS Code use to programmatically "open" files and generate TypeScript programs for type information.

 :::note
 See [Announcing typescript-eslint v8 >Project Service](/blog/announcing-typescript-eslint-v8#project-service) for more details on how lint users interact with the Project Service.
 See [Blog > Typed Linting withProject Service](/blog/project-service) for more details on how lint users interact with the Project Service.
 :::

 ```ts
diff --git a/packages/website/blog/2025-05-26-project-service.mdx b/packages/website/blog/2025-05-26-project-service.mdx
 ---
 authors: joshuakgoldberg
 description: How typescript-eslint's new "Project Service" makes typed linting easier to configure, especially for large projects.
 slug: project-service
 tags: [parser, parser options, project, project service, tsconfig]
 title: Typed Linting with Project Service
 ---

 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';

 ["Typed linting"](/blog/typed-linting), or enabling ESLint rules to understand TypeScript types, is one of the best parts of typescript-eslint.
 It enables a slew of more powerful lint rules that check for nuanced bugs, best practice violations, and other code issues that can only be detected using type information.

 Typed linting hasn't always been straightforward to configure or performant at runtime.
 We've seen users have to manage separate `tsconfig.eslint.json` files to enable typed linting — sometimes with different compiler options than the rest of the project.
 Not ideal.

 In typescript-eslint 8.0, we stabilized a **`parserOptions.projectService`** option that uses more powerful, streamlined TypeScript APIs than before.
 The "Project Service" brings several benefits:

 - ✍️ **Configuration**: simpler ESLint configs for typed linting with no ESLint-specific TSConfig files
 - 🧠 **Predictability**: uses the same type information services as editors, including more reliability
 - 🚀 **Scalability**: supporting TypeScript project references for larger repositories (i.e. monorepos)

 This blog post will cover how `parserOptions.projectService` simplifies configurations and aligns linting type information to what editors such as VS Code run with.

 :::tip
 See [Getting Started](/getting-started) to learn how to lint JavaScript and TypeScript code with typescript-eslint, then [Linting with Type Information](/getting-started/typed-linting) to onboard to typed linting.
 :::

 <!-- truncate -->

 ## Introducing the Project Service

 Back in [Relative TSConfig Projects with `parserOptions.project = true` > Project Services](2023-09-18-parser-options-project-true.md#project-services), we'd mentioned a replacement for `parserOptions.project`:

 > The downside of having users specify `parserOptions.project` at all is that `@typescript-eslint/parser` needs manual logic to create TypeScript Programs and associate them with linted files.
 > Manual Program creation logic comes with a few issues: ...
 >
 > We're working on an option to instead call the same TypeScript "Project Service" APIs that editors such as VS Code use to create Programs for us instead.
 > Project Services 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`).

 Following a year of discussion and beta testing in typescript-eslint v6 and v7, we believe the new Project Service API is ready to be used by real-world projects.
 We therefore promoted the `parserOptions.EXPERIMENTAL_useProjectService` option to the stable name **`parserOptions.projectService`** in typescript-eslint v8.

 :::note
 See [Announcing typescript-eslint v8 > Project Service](/blog/announcing-typescript-eslint-v8#project-service) for the original announcement.
 :::

 ## Configuration

 You can change over to the new Project Service API by replacing `project` with `projectService` in your ESLint configuration:

 <Tabs groupId="eslint-config">
 <TabItem value="Flat Config">

 ```js title="eslint.config.js"
 export default tseslint.config({
  // ...
  languageOptions: {
    parserOptions: {
      // Remove this line
      project: true,
      // Add this line
      projectService: true,
    },
  },
  // ...
 });
 ```

 </TabItem>
 <TabItem value="Legacy Config">

 ```js title=".eslintrc.cjs"
 module.exports = {
  // ...
  parser: '@typescript-eslint/parser',
  parserOptions: {
    // Remove this line
    project: true,
    // Add this line
    projectService: true,
  },
  // ...
 };
 ```

 </TabItem>
 </Tabs>

 That's it!

 Other settings, including how you run ESLint and configure rules, should work the same.

 :::tip
 See [Packages > Parser > `projectService`](/packages/parser#projectservice) for more details on granular configuration options.
 :::

 ### Additional Files

 One long-standing pain point of typed linting was enabling typed linting for files not included in the project's `tsconfig.json`.
 Common solutions in the traditional Program API were to either skip typed linting for those files or to create a `tsconfig.eslint.json` enabling the `allowJs` compiler option.

 The new Project Service API allows for a configuration object specifying `allowDefaultProject`: a glob of "out-of-project" files to lint with type information.
 That means you can lint those files without any new configuration files or TypeScript compiler options!

 For example, the following config solves the common case of projects that have root-level files like `eslint.config.js` or `vitest.config.ts`:

 <Tabs groupId="eslint-config">
 <TabItem value="Flat Config">

 ```js title="eslint.config.js"
 export default tseslint.config({
  // ...
  languageOptions: {
    parserOptions: {
      projectService: {
        allowDefaultProject: ['*.js'],
      },
    },
  },
  // ...
 });
 ```

 </TabItem>
 <TabItem value="Legacy Config">

 ```js title=".eslintrc.cjs"
 module.exports = {
  // ...
  parser: '@typescript-eslint/parser',
  parserOptions: {
    projectService: {
      allowDefaultProject: ['*.js'],
    },
  },
  // ...
 };
 ```

 </TabItem>
 </Tabs>

 This means most projects should be able to remove all `tsconfig.eslint.json` files!
 🥳

 :::tip
 See [Packages > Parser > `projectService` > `ProjectServiceOptions`](/packages/parser#projectserviceOptions) for more details on out-of-project files and other granular configuration options.
 :::

 ## Predictability

 We've found configuring `tsconfig.eslint.json` files to be a common source of confusion with the traditional Program APIs.
 They can result in the type information used for _linting_ accidentally being different from the type information used for _type checking_.
 Unifying TypeScript configurations to the same `tsconfig.json` file(s) altogether avoids potential divergent types.

 Another benefit of using the new Project Service API is that typed linting requires no additional work in typescript-eslint for more difficult uses of ESLint and/or TypeScript.
 We sometimes had to de-optimize the traditional Program API to support use cases:

 - CLI `--fix` mode would lose type information after the first pass ([#9577](https://github.com/typescript-eslint/typescript-eslint/pull/9577))
 - Extra file extensions such as `.svelte` and `.vue` were not supported at all ([#9504](https://github.com/typescript-eslint/typescript-eslint/issues/9504))

 The new Project Service API does not suffer from these issues.
 It supports extra file extensions out-of-the-box and does not slow down when used with ESLint's `--fix`.

 ## Scalability

 [TypeScript's project references](https://www.typescriptlang.org/docs/handbook/project-references.html) are how many larger projects, in particular monorepos, scale TypeScript type checking.
 They allow delineating discrete projects with their own `tsconfig.json` files and annotating which projects depend on which other projects.
 TypeScript is able to cache type information and only recheck projects that have changed in builds based on those project references.

 The traditional `parserOptions.project` API did not support project references for typed linting.
 We had experimented with adding support, but using the manual built-in TypeScript APIs would have been a significant maintenance investment with an unclear payoff.

 The new Project Service API does support project references out-of-the-box.
 This is a huge win for monorepos, as it means you can lint all of your projects with type information without needing to create a separate `tsconfig.eslint.json` file for each project.

 ## Performance

 Supporting project references allows the new Project Service API to be significantly faster than the traditional `parserOptions.project` API in many monorepo cases.
 We've observed improvements for typed linting speed in real-world repositories [^1] [^2].
 For smaller projects, the performance of the new Project Service API is similar to the traditional `parserOptions.project` API.

 When we first started working with the new project service API, it outperformed equivalent `parserOptions.project` setups by ~10-15%.
 Since then, we have observed regressions in performance that have brought it down in some cases to be slightly slower.

 We believe the new Project Service API should be faster than the traditional API, and are treating the lack of significant improvement as a bug.
 See [⚡ Performance: parserOptions.projectService sometimes no longer outperforms parserOptions.project](https://github.com/typescript-eslint/typescript-eslint/issues/9571) for more information.

 ## Next Steps

 The new Project Service API is available in typescript-eslint v8.0.0 and later.
 We've been using it in our monorepo for over a year and have been thrilled to see many community repositories adopt it as well.

 ### Giving Feedback

 We'd love to hear from you on how this option works for you.
 Does it live up to what we've promised, and/or does it have bugs we haven't fixed yet?
 Please do send us GitHub issues for any bugs you encounter or suggestions for how to improve the API.

 The [typescript-eslint Discord](https://discord.gg/FSxKq8Tdyg) is a great place to ask questions and engage with us more casually.
 For support in onboarding, feel free to ask in its `#help` channel.
 We'd be happy to help you try out `parserOptions.projectService` and learn more about how you use typescript-eslint.

 ### Long Term Vision

 The new Project Service API is a great step towards making typed linting easier and more straightforward to configure.
 Our priority for the next year will be to improve the new Project Service API so that it works in all places the traditional Program API does.
 We won't remove the traditional project program behavior unless and until the new Project Service API is able to fully replace it.

 As of typescript-eslint@8.33.0, we've also extracted most of the Project Service code into a standalone [`@typescript-eslint/project-service`](/packages/project-service) package.
 It has no dependencies on ESLint and is designed to be usable for any linter to enable TypeScript's Project Service API for typed linting.
 See [Packages > Project Service](/packages/project-service) for more details.

 We're also looking forward to investigating support for [TypeScript's 10x faster Go port](https://github.com/typescript-eslint/typescript-eslint/issues/10940).
 Abstracting configuration details into the Project Service API means it will be much easier for typescript-eslint to support typed linting using "tsgo" without any additional user configuration.

 So, please, try out the new Project Service API.
 We're excited to hear how it works for you and what we can do to improve it. 💜

 [^1]: https://github.com/babel/babel/pull/16192#issue-2054613116

 [^2]: https://github.com/t3-oss/create-t3-app/pull/1936/#discussion_r1667389041
Original file line number	Diff line number	Diff line change
Expand Up		@@ -196,6 +196,7 @@
		"tsconfigrootdir",
		"tsconfigs",
		"tseslint",
		"tsgo",
		"tsvfs",
		"typedef",
		"typedefs",
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -294,6 +294,8 @@ Specifies using TypeScript APIs to generate type information for rules.
		It will automatically use the nearest `tsconfig.json` for each file (like `project: true`).
		It can also be configured to also allow type information to be computed for JavaScript files without the `allowJs` compiler option (unlike `project: true`).

		See [Typed Linting with `parserOptions.projectService`](/blog/project-service) for more context.

		<Tabs groupId="eslint-config">
		<TabItem value="Flat Config">

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -16,7 +16,7 @@ The typescript-eslint Project Service is a wrapper around TypeScript's "project
		These APIs are what editors such as VS Code use to programmatically "open" files and generate TypeScript programs for type information.

		:::note
		See [Announcing typescript-eslint v8 >Project Service](/blog/announcing-typescript-eslint-v8#project-service) for more details on how lint users interact with the Project Service.
		See [Blog > Typed Linting withProject Service](/blog/project-service) for more details on how lint users interact with the Project Service.
		:::

		```ts
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,226 @@
		---
		authors: joshuakgoldberg
		description: How typescript-eslint's new "Project Service" makes typed linting easier to configure, especially for large projects.
		slug: project-service
		tags: [parser, parser options, project, project service, tsconfig]
		title: Typed Linting with Project Service
		---

		import Tabs from '@theme/Tabs';
		import TabItem from '@theme/TabItem';

		["Typed linting"](/blog/typed-linting), or enabling ESLint rules to understand TypeScript types, is one of the best parts of typescript-eslint.
		It enables a slew of more powerful lint rules that check for nuanced bugs, best practice violations, and other code issues that can only be detected using type information.

		Typed linting hasn't always been straightforward to configure or performant at runtime.
		We've seen users have to manage separate `tsconfig.eslint.json` files to enable typed linting — sometimes with different compiler options than the rest of the project.
		Not ideal.

		In typescript-eslint 8.0, we stabilized a `parserOptions.projectService` option that uses more powerful, streamlined TypeScript APIs than before.
		The "Project Service" brings several benefits:

		- ✍️ Configuration: simpler ESLint configs for typed linting with no ESLint-specific TSConfig files
		- 🧠 Predictability: uses the same type information services as editors, including more reliability
		- 🚀 Scalability: supporting TypeScript project references for larger repositories (i.e. monorepos)

		This blog post will cover how `parserOptions.projectService` simplifies configurations and aligns linting type information to what editors such as VS Code run with.

		:::tip
		See [Getting Started](/getting-started) to learn how to lint JavaScript and TypeScript code with typescript-eslint, then [Linting with Type Information](/getting-started/typed-linting) to onboard to typed linting.
		:::

		<!-- truncate -->

		## Introducing the Project Service

		Back in [Relative TSConfig Projects with `parserOptions.project = true` > Project Services](2023-09-18-parser-options-project-true.md#project-services), we'd mentioned a replacement for `parserOptions.project`:

		> The downside of having users specify `parserOptions.project` at all is that `@typescript-eslint/parser` needs manual logic to create TypeScript Programs and associate them with linted files.
		> Manual Program creation logic comes with a few issues: ...
		>
		> We're working on an option to instead call the same TypeScript "Project Service" APIs that editors such as VS Code use to create Programs for us instead.
		> Project Services 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`).

		Following a year of discussion and beta testing in typescript-eslint v6 and v7, we believe the new Project Service API is ready to be used by real-world projects.
		We therefore promoted the `parserOptions.EXPERIMENTAL_useProjectService` option to the stable name `parserOptions.projectService` in typescript-eslint v8.

		:::note
		See [Announcing typescript-eslint v8 > Project Service](/blog/announcing-typescript-eslint-v8#project-service) for the original announcement.
		:::

		## Configuration

		You can change over to the new Project Service API by replacing `project` with `projectService` in your ESLint configuration:

		<Tabs groupId="eslint-config">
		<TabItem value="Flat Config">

		```js title="eslint.config.js"
		export default tseslint.config({
		// ...
		languageOptions: {
		parserOptions: {
		// Remove this line
		project: true,
		// Add this line
		projectService: true,
		},
		},
		// ...
		});
		```

		</TabItem>
		<TabItem value="Legacy Config">

		```js title=".eslintrc.cjs"
		module.exports = {
		// ...
		parser: '@typescript-eslint/parser',
		parserOptions: {
		// Remove this line
		project: true,
		// Add this line
		projectService: true,
		},
		// ...
		};
		```

		</TabItem>
		</Tabs>

		That's it!

		Other settings, including how you run ESLint and configure rules, should work the same.

		:::tip
		See [Packages > Parser > `projectService`](/packages/parser#projectservice) for more details on granular configuration options.
		:::

		### Additional Files

		One long-standing pain point of typed linting was enabling typed linting for files not included in the project's `tsconfig.json`.
		Common solutions in the traditional Program API were to either skip typed linting for those files or to create a `tsconfig.eslint.json` enabling the `allowJs` compiler option.

		The new Project Service API allows for a configuration object specifying `allowDefaultProject`: a glob of "out-of-project" files to lint with type information.
		That means you can lint those files without any new configuration files or TypeScript compiler options!

		For example, the following config solves the common case of projects that have root-level files like `eslint.config.js` or `vitest.config.ts`:

		<Tabs groupId="eslint-config">
		<TabItem value="Flat Config">

		```js title="eslint.config.js"
		export default tseslint.config({
		// ...
		languageOptions: {
		parserOptions: {
		projectService: {
		allowDefaultProject: ['*.js'],
		},
		},
		},
		// ...
		});
		```

		</TabItem>
		<TabItem value="Legacy Config">

		```js title=".eslintrc.cjs"
		module.exports = {
		// ...
		parser: '@typescript-eslint/parser',
		parserOptions: {
		projectService: {
		allowDefaultProject: ['*.js'],
		},
		},
		// ...
		};
		```

		</TabItem>
		</Tabs>

		This means most projects should be able to remove all `tsconfig.eslint.json` files!
		🥳

		:::tip
		See [Packages > Parser > `projectService` > `ProjectServiceOptions`](/packages/parser#projectserviceOptions) for more details on out-of-project files and other granular configuration options.
		:::

		## Predictability

		We've found configuring `tsconfig.eslint.json` files to be a common source of confusion with the traditional Program APIs.
		They can result in the type information used for _linting_ accidentally being different from the type information used for _type checking_.
		Unifying TypeScript configurations to the same `tsconfig.json` file(s) altogether avoids potential divergent types.

		Another benefit of using the new Project Service API is that typed linting requires no additional work in typescript-eslint for more difficult uses of ESLint and/or TypeScript.
		We sometimes had to de-optimize the traditional Program API to support use cases:

		- CLI `--fix` mode would lose type information after the first pass ([#9577](https://github.com/typescript-eslint/typescript-eslint/pull/9577))
		- Extra file extensions such as `.svelte` and `.vue` were not supported at all ([#9504](https://github.com/typescript-eslint/typescript-eslint/issues/9504))

		The new Project Service API does not suffer from these issues.
		It supports extra file extensions out-of-the-box and does not slow down when used with ESLint's `--fix`.

		## Scalability

		[TypeScript's project references](https://www.typescriptlang.org/docs/handbook/project-references.html) are how many larger projects, in particular monorepos, scale TypeScript type checking.
		They allow delineating discrete projects with their own `tsconfig.json` files and annotating which projects depend on which other projects.
		TypeScript is able to cache type information and only recheck projects that have changed in builds based on those project references.

		The traditional `parserOptions.project` API did not support project references for typed linting.
		We had experimented with adding support, but using the manual built-in TypeScript APIs would have been a significant maintenance investment with an unclear payoff.

		The new Project Service API does support project references out-of-the-box.
		This is a huge win for monorepos, as it means you can lint all of your projects with type information without needing to create a separate `tsconfig.eslint.json` file for each project.

		## Performance

		Supporting project references allows the new Project Service API to be significantly faster than the traditional `parserOptions.project` API in many monorepo cases.
		We've observed improvements for typed linting speed in real-world repositories [^1] [^2].
		For smaller projects, the performance of the new Project Service API is similar to the traditional `parserOptions.project` API.

		When we first started working with the new project service API, it outperformed equivalent `parserOptions.project` setups by ~10-15%.
		Since then, we have observed regressions in performance that have brought it down in some cases to be slightly slower.

		We believe the new Project Service API should be faster than the traditional API, and are treating the lack of significant improvement as a bug.
		See [⚡ Performance: parserOptions.projectService sometimes no longer outperforms parserOptions.project](https://github.com/typescript-eslint/typescript-eslint/issues/9571) for more information.

		## Next Steps

		The new Project Service API is available in typescript-eslint v8.0.0 and later.
		We've been using it in our monorepo for over a year and have been thrilled to see many community repositories adopt it as well.

		### Giving Feedback

		We'd love to hear from you on how this option works for you.
		Does it live up to what we've promised, and/or does it have bugs we haven't fixed yet?
		Please do send us GitHub issues for any bugs you encounter or suggestions for how to improve the API.

		The [typescript-eslint Discord](https://discord.gg/FSxKq8Tdyg) is a great place to ask questions and engage with us more casually.
		For support in onboarding, feel free to ask in its `#help` channel.
		We'd be happy to help you try out `parserOptions.projectService` and learn more about how you use typescript-eslint.

		### Long Term Vision

		The new Project Service API is a great step towards making typed linting easier and more straightforward to configure.
		Our priority for the next year will be to improve the new Project Service API so that it works in all places the traditional Program API does.
		We won't remove the traditional project program behavior unless and until the new Project Service API is able to fully replace it.

		As of typescript-eslint@8.33.0, we've also extracted most of the Project Service code into a standalone [`@typescript-eslint/project-service`](/packages/project-service) package.
		It has no dependencies on ESLint and is designed to be usable for any linter to enable TypeScript's Project Service API for typed linting.
		See [Packages > Project Service](/packages/project-service) for more details.
Copy link MemberAuthor JoshuaKGoldbergMay 21, 2025 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Note that#10383 (comment) proposes a pretty big shake-up in other packages. I don't think it impacts this though. Just an FYI :)

		We're also looking forward to investigating support for [TypeScript's 10x faster Go port](https://github.com/typescript-eslint/typescript-eslint/issues/10940).
		Abstracting configuration details into the Project Service API means it will be much easier for typescript-eslint to support typed linting using "tsgo" without any additional user configuration.

		So, please, try out the new Project Service API.
		We're excited to hear how it works for you and what we can do to improve it. 💜

		[^1]: https://github.com/babel/babel/pull/16192#issue-2054613116

		[^2]: https://github.com/t3-oss/create-t3-app/pull/1936/#discussion_r1667389041