feat(typescript): extract extend global types to its own section

src/content/docs/en/guides/cms/builderio.mdx

@@ -9,6 +9,7 @@ stub: false
 i18nReady: true
 ---
 import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
+import ReadMore from '~/components/ReadMore.astro';
 import { FileTree } from '@astrojs/starlight/components';
 import { Steps } from '@astrojs/starlight/components';
 
@@ -57,6 +58,7 @@ Your project should now include these files:
 - package.json
 </FileTree>
 
+<ReadMore>Learn more about [environment variables](/en/guides/environment-variables/) and `.env` files in Astro.</ReadMore>
 
 ## Making a blog with Astro and Builder
 

src/content/docs/en/guides/cms/datocms.mdx

@@ -10,6 +10,7 @@ i18nReady: true
 ---
 import { Steps } from '@astrojs/starlight/components';
 import { FileTree } from '@astrojs/starlight/components';
+import ReadMore from '~/components/ReadMore.astro';
 
 [DatoCMS](https://datocms.com/) is a web-based, headless CMS to manage digital content for your sites and apps.
 
@@ -51,6 +52,8 @@ Your root directory should now include these files:
 - package.json
 </FileTree>
 
+<ReadMore>Learn more about [environment variables](/en/guides/environment-variables/) and `.env` files in Astro.</ReadMore>
+
 ## Create a Model in DatoCMS
 
 In the DatoCMS admin dashboard of your project, navigate to "Settings" > "Models" and create a new Model called "Home" with the "Single Instance" toggle selected. This will create a home page for your project. In this model, add a new text field for the page title.

src/content/docs/en/guides/cms/strapi.mdx

@@ -11,6 +11,7 @@ i18nReady: true
 import { Steps } from '@astrojs/starlight/components';
 import { FileTree } from '@astrojs/starlight/components';
 import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
+import ReadMore from '~/components/ReadMore.astro';
 
 [Strapi](https://strapi.io/) is an open-source, customizable, headless CMS.
 
@@ -52,6 +53,8 @@ Your root directory should now include the new file(s):
   - package.json
 </FileTree>
 
+<ReadMore>Learn more about [environment variables](/en/guides/environment-variables/) and `.env` files in Astro.</ReadMore>
+
 ### Creating the API wrapper
 
 Create a new file at `src/lib/strapi.ts` and add the following wrapper function to interact with the Strapi API:

src/content/docs/en/guides/environment-variables.mdx

@@ -35,7 +35,7 @@ By default, Astro provides a type definition for `import.meta.env` in `astro/cli
 
 While you can define more custom env variables in `.env.[mode]` files, you may want to get TypeScript IntelliSense for user-defined env variables which are prefixed with `PUBLIC_`.
 
-To achieve this, you can create an `env.d.ts` in `src/` and configure `ImportMetaEnv` like this:
+To achieve this, you can create an `env.d.ts` in `src/` to [extend the global types](/en/guides/typescript/#extending-global-types) and configure `ImportMetaEnv` like this:
 
 ```ts title="src/env.d.ts"
 interface ImportMetaEnv {

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

@@ -148,7 +148,7 @@ The following example adds [Alpine's Collapse plugin](https://alpinejs.dev/plugi
 
 ## Intellisense for TypeScript
 
-The `@astrojs/alpine` integration adds `Alpine` to the global window object. For IDE autocompletion, add the following to your `src/env.d.ts`:
+The `@astrojs/alpine` integration adds `Alpine` to [the global window object](/en/guides/typescript/#window-and-globalthis). For IDE autocompletion, add the following to your `src/env.d.ts`:
 
 ```ts title="src/env.d.ts"
 interface Window {

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

@@ -428,7 +428,7 @@ You can create a pnpm script to run `wrangler types` automatically before other
 ```
 :::
 
-You can type the `runtime` object using `Runtime`:
+You can type the `runtime` object by [extending global types](/en/guides/typescript/#extending-global-types) using `Runtime`:
 
 ```ts title="src/env.d.ts"
 type Runtime = import('@astrojs/cloudflare').Runtime<Env>;

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

@@ -134,7 +134,7 @@ const {
 <h1>Hello there, friendly visitor from {city}!</h1>
 ```
 
-If you're using TypeScript, you can get proper typings by updating `src/env.d.ts` to use `NetlifyLocals`:
+If you're using TypeScript, you can [get proper typings](/en/guides/typescript/#extending-global-types) by updating `src/env.d.ts` to use `NetlifyLocals`:
 
 ```ts title="src/env.d.ts"
 type NetlifyLocals = import('@astrojs/netlify').NetlifyLocals

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

@@ -382,7 +382,7 @@ 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`:
+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](/en/guides/typescript/#extending-global-types) by updating `src/env.d.ts` to use `EdgeLocals`:
 
 ```ts
 type EdgeLocals = import('@astrojs/vercel').EdgeLocals

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

@@ -139,7 +139,7 @@ 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:
+To type the information inside `Astro.locals`, which gives you autocompletion inside `.astro` files and middleware code, [extend the global types](/en/guides/typescript/#extending-global-types) by declaring a global namespace in the `env.d.ts` file:
 
 ```ts title="src/env.d.ts"
 type User = {

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

@@ -126,7 +126,7 @@ export const onRequest = defineMiddleware(async (context, next) => {
 
 By default session data is untyped, and you can store arbitrary data in any key. Values are serialized and deserialized using [devalue](https://github.com/Rich-Harris/devalue), which is the same library used in content collections and actions. This means that supported types are the same, and include strings, numbers, `Date`, `Map`, `Set`, `URL`, arrays, and plain objects.
 
-You can optionally define TypeScript types for your session data by creating a `src/env.d.ts` file and adding a declaration for the `App.SessionData` type:
+You can optionally [define TypeScript types](/en/guides/typescript/#extending-global-types) for your session data by creating a `src/env.d.ts` file and adding a declaration for the `App.SessionData` type:
 
 ```ts title="src/env.d.ts"
 declare namespace App {

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

@@ -40,16 +40,6 @@ Additionally, we recommend setting `include` and `exclude` as follows to benefit
 }
 ```
 
-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 VS Code extension, and you do not need to install both.
@@ -118,7 +108,7 @@ You can configure TypeScript to enforce type imports in your `tsconfig.json` fil
 
 ## Import Aliases
 
-Astro supports [import aliases](/en/guides/imports/#aliases) that you define in your `tsconfig.json` `paths` configuration. [Read our guide](/en/guides/imports/#aliases) to learn more.
+Astro supports import aliases that you define in your `tsconfig.json` `paths` configuration. [Read our imports guide](/en/guides/imports/#aliases) to learn more.
 
 ```astro title="src/pages/about/nate.astro" "@components" "@layouts"
 ---
@@ -138,7 +128,19 @@ import Layout from "@layouts/Layout.astro";
 }
 ```
 
-## Extending `window` and `globalThis`
+## Extending global types
+
+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" />
+```
+
+### `window` and `globalThis`
 
 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:
 
@@ -159,6 +161,56 @@ interface Window {
 }
 ```
 
+### Add non-standard attributes
+
+You may want to define a type for custom attributes or CSS properties. You can extend the default JSX definitions to add non-standard attributes by redeclaring the `astroHTML.JSX` namespace in a `.d.ts` file.
+
+```ts title="src/env.d.ts"
+declare namespace astroHTML.JSX {
+  interface HTMLAttributes {
+    "data-count"?: number;
+    "data-label"?: string;
+  }
+
+  // Add a CSS custom property to the style object
+  interface CSSProperties {
+    "--theme-color"?: "black" | "white";
+  }
+}
+```
+
+:::note
+`astroHTML` is injected globally inside `.astro` components. To use it in TypeScript files, use a [triple-slash directive](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html):
+
+```ts
+/// <reference types="astro/astro-jsx" />
+
+type MyAttributes = astroHTML.JSX.ImgHTMLAttributes;
+```
+:::
+
+### Using imports
+
+You may want to extend global types by reusing types declared elsewhere in your project or from an external library. To do this, use [dynamic imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import):
+
+```ts title="src/env.d.ts"
+type Product = {
+  id: string;
+  name: string;
+  price: number;
+};
+
+declare namespace App {
+  interface Locals {
+    orders: Map<string, Product[]>
+    session: import("./lib/server/session").Session | null;
+    user: import("my-external-library").User;
+  }
+}
+```
+
+A `.d.ts` file is an [ambient module](https://www.typescriptlang.org/docs/handbook/modules/reference.html#ambient-modules) declaration. While its syntax is similar to ES modules, these files do not allow top-level imports/exports. If Typescript encounters one, the file will be considered a [module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation) and this will break your global types.
+
 ## Component Props
 
 Astro supports typing your component props via TypeScript. To enable, add a TypeScript `Props` interface to your component frontmatter. An `export` statement may be used, but is not necessary. The [Astro VS Code Extension](/en/editor-setup/) will automatically look for the `Props` interface and give you proper TS support when you use that component inside another template.
@@ -211,32 +263,6 @@ const { href, ...attrs } = Astro.props;
 </a>
 ```
 
-It is also possible to extend the default JSX definitions to add non-standard attributes by redeclaring the `astroHTML.JSX` namespace in a `.d.ts` file.
-
-```ts title="src/custom-attributes.d.ts"
-declare namespace astroHTML.JSX {
-  interface HTMLAttributes {
-    "data-count"?: number;
-    "data-label"?: string;
-  }
-
-  // Add a CSS custom property to the style object
-  interface CSSProperties {
-    "--theme-color"?: "black" | "white";
-  }
-}
-```
-
-:::note
-`astroHTML` is injected globally inside `.astro` components. To use it in TypeScript files, use a [triple-slash directive](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html):
-
-```ts
-/// <reference types="astro/astro-jsx" />
-
-type MyAttributes = astroHTML.JSX.ImgHTMLAttributes;
-```
-:::
-
 ### `ComponentProps` type
 
 <p><Since v="4.3.0" /></p>