feat(next): better tsconfig docs

src/content/docs/en/guides/integrations-guide/cloudflare.mdx

@@ -289,8 +289,6 @@ You can create a pnpm script to run `wrangler types` automatically before other
 You can type the `runtime` object using `Runtime`:
 
 ```ts title="src/env.d.ts"
-/// <reference types="astro/client" />
-
 type Runtime = import('@astrojs/cloudflare').Runtime<Env>;
 
 declare namespace App {

src/content/docs/en/guides/integrations-guide/netlify.mdx

@@ -111,9 +111,6 @@ const {
 If you're using TypeScript, you can get proper typings by updating `src/env.d.ts` to use `NetlifyLocals`:
 
 ```ts title="src/env.d.ts"
-/// <reference path="../.astro/types.d.ts" />
-/// <reference types="astro/client" />
-
 type NetlifyLocals = import('@astrojs/netlify').NetlifyLocals
 
 declare namespace App {

src/content/docs/en/guides/integrations-guide/vercel.mdx

@@ -398,9 +398,6 @@ export default defineConfig({
 The edge middleware has access to Vercel's [`RequestContext`](https://vercel.com/docs/functions/edge-middleware/middleware-api#requestcontext) as `ctx.locals.vercel.edge`. If you’re using TypeScript, you can get proper typings by updating `src/env.d.ts` to use `EdgeLocals`:
 
 ```ts
-/// <reference path="../.astro/types.d.ts" />
-/// <reference types="astro/client" />
-
 type EdgeLocals = import('@astrojs/vercel').EdgeLocals
 
 declare namespace App {

src/content/docs/en/guides/middleware.mdx

@@ -140,7 +140,6 @@ export const onRequest = (context, next) => {
 To type the information inside `Astro.locals`, which gives you autocompletion inside `.astro` files and middleware code, declare a global namespace in the `env.d.ts` file:
 
 ```ts title="src/env.d.ts"
-/// <reference types="astro/client" />
 declare namespace App {
     interface Locals {
         user: {

src/content/docs/en/guides/typescript.mdx

@@ -15,26 +15,44 @@ You don't need to write TypeScript code in your Astro projects to benefit from i
 The Astro dev server won't perform any type checking, but you can use a [separate script](#type-checking) to check for type errors from the command line.
 
 ## Setup
+
 Astro starter projects include a `tsconfig.json` file in your project. Even if you don't write TypeScript code, this file is important so that tools like Astro and VS Code know how to understand your project. Some features (like npm package imports) aren't fully supported in the editor without a `tsconfig.json` file. If you install Astro manually, be sure to create this file yourself.
 
+### TSConfig templates
+
 Three extensible `tsconfig.json` templates are included in Astro: `base`, `strict`, and `strictest`. The `base` template enables support for modern JavaScript features and is also used as a basis for the other templates. We recommend using `strict` or `strictest` if you plan to write TypeScript in your project. You can view and compare the three template configurations at [astro/tsconfigs/](https://github.com/withastro/astro/blob/main/packages/astro/tsconfigs/).
 
 To inherit from one of the templates, use [the `extends` setting](https://www.typescriptlang.org/tsconfig#extends):
-
 ```json title="tsconfig.json"
 {
   "extends": "astro/tsconfigs/base"
 }
 ```
 
-Additionally, our templates include an `env.d.ts` file inside the `src` folder to provide [Vite's client types](https://vitejs.dev/guide/features.html#client-types) to your project:
+Additionally, we recommend setting `include` and `exclude` as follows to benefit from Astro types and avoid checking built files:
 
-```typescript title="env.d.ts"
-/// <reference types="astro/client" />
+```json title="tsconfig.json" ins={3-4}
+{
+  "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
+}
 ```
 
-If you are not using VSCode, you can install the [Astro TypeScript plugin](https://www.npmjs.com/package/@astrojs/ts-plugin) to support importing `.astro` files from `.ts` files (which can be useful for re-exporting).
+You can create `src/env.d.ts` as a convention for adding custom types declarations, or to benefit from Astro types if you don't have a `tsconfig.json`:
+
+```ts title="src/env.d.ts"
+// Custom types declarations
+declare var myString: string;
 
+// Astro types, not necessary if you already have a tsconfig.json
+/// <reference path="../.astro/types.d.ts" />
+```
+
+### TypeScript editor plugin
+The [Astro TypeScript plugin](https://www.npmjs.com/package/@astrojs/ts-plugin) can be installed separately when you are not using the [official Astro VS Code extension](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode). This plugin is automatically installed and configured by the VSCode extension, and you do not need to install both.
+This plugin runs only in the editor. When running `tsc` in the terminal, `.astro` files are ignored entirely. Instead, you can use [the `astro check` CLI command](/en/reference/cli-reference/#astro-check) to check both `.astro` and `.ts` files.
+This plugin also supports importing `.astro` files from `.ts` files (which can be useful for re-exporting).
 <PackageManagerTabs>
   <Fragment slot="npm">
   ```shell
@@ -52,9 +70,7 @@ If you are not using VSCode, you can install the [Astro TypeScript plugin](https
   ```
   </Fragment>
 </PackageManagerTabs>
-
 Then, add the following to your `tsconfig.json`:
-
 ```json title="tsconfig.json"
   "compilerOptions": {
     "plugins": [
@@ -64,10 +80,8 @@ Then, add the following to your `tsconfig.json`:
     ],
   }
 ```
-
 To check that the plugin is working, create a `.ts` file and import an Astro component into it. You should have no warning messages from your editor.
 
-
 ### UI Frameworks
 
 If your project uses a [UI framework](/en/guides/framework-components/), additional settings depending on the framework might be needed. Please see your framework's TypeScript documentation for more information. ([Vue](https://vuejs.org/guide/typescript/overview.html#using-vue-with-typescript), [React](https://react-typescript-cheatsheet.netlify.app/docs/basic/setup), [Preact](https://preactjs.com/guide/v10/typescript), [Solid](https://www.solidjs.com/guides/typescript))
@@ -121,7 +135,7 @@ import Layout from '@layouts/Layout.astro';
 
 You may want to add a property to the global object. You can do this by adding top-level declarations using the `declare` keyword to your `env.d.ts` file:
 
-```ts title="env.d.ts"
+```ts title="src/env.d.ts"
 declare const myString: string;
 declare function myFunction(): boolean;
 ```
@@ -132,7 +146,7 @@ Note that `window` is only available in client-side code. `globalThis` is availa
 
 If you only want to type a property on the `window` object, provide a `Window` interface instead:
 
-```ts title="env.d.ts"
+```ts title="src/env.d.ts"
 interface Window {
 	myFunction(): boolean;
 }

src/content/docs/en/reference/cli-reference.mdx

@@ -260,7 +260,7 @@ Specifies not to clear the ouput between checks when in watch mode.
 Running `astro dev`, `astro build` or `astro check` will run the `sync` command as well.
 :::
 
-Generates TypeScript types for all Astro modules. This sets up a [`src/env.d.ts` file](/en/guides/typescript/#setup) for type inferencing, and defines modules for features that rely on generated types:
+Generates TypeScript types for all Astro modules. This sets up a [`.astro/types.d.ts` file](/en/guides/typescript/#setup) for type inferencing, and defines modules for features that rely on generated types:
 - The `astro:content` module for the [Content Collections API](/en/guides/content-collections/).
 - The `astro:db` module for [Astro DB](/en/guides/astro-db/).