docs: better documentation for `runtime` (#8190)

4 files changed, 55 insertions, 5 deletions

diff --git a/packages/integrations/cloudflare/README.md b/packages/integrations/cloudflare/README.md
index 61db6effc..f5a939b29 100644
--- a/packages/integrations/cloudflare/README.md
+++ b/packages/integrations/cloudflare/README.md
@@ -75,12 +75,59 @@ It's then possible to update the preview script in your `package.json` to `"prev
 
 You can access all the Cloudflare bindings and environment variables from Astro components and API routes through `Astro.locals`.
 
-```js
+If you're inside an `.astro` file, you access the runtime using the `Astro.locals` global:
+
+```astro
 const env = Astro.locals.runtime.env;
 ```
 
+From an endpoint:
+
+```js
+// src/pages/api/someFile.js
+export function get(context) {
+    const runtime = context.locals.runtime;
+    
+    return new Response("Some body");
+}
+```
+
 Depending on your adapter mode (advanced = worker, directory = pages), the runtime object will look a little different due to differences in the Cloudflare API.
 
+If you're using the `advanced` runtime, you can type the `runtime` object as following:
+
+```ts
+// src/env.d.ts
+/// <reference types="astro/client" />
+import type { AdvancedRuntime } from "@astrojs/cloudflare"
+
+declare namespace App {
+  interface Locals extends AdvancedRuntime {
+    user: {
+      name: string;
+      surname: string;
+    };
+  }
+}
+```
+
+If you're using the `directory` runtime, you can type the `runtime` object as following:
+
+```ts
+// src/env.d.ts
+/// <reference types="astro/client" />
+import type { DirectoryRuntime } from "@astrojs/cloudflare"
+
+declare namespace App {
+  interface Locals extends DirectoryRuntime {
+    user: {
+      name: string;
+      surname: string;
+    };
+  }
+}
+```
+
 ## Environment Variables
 
 See Cloudflare's documentation for [working with environment variables](https://developers.cloudflare.com/pages/platform/functions/bindings/#environment-variables).
diff --git a/packages/integrations/cloudflare/src/index.ts b/packages/integrations/cloudflare/src/index.ts
index 5f02184fa..a0201008f 100644
--- a/packages/integrations/cloudflare/src/index.ts
+++ b/packages/integrations/cloudflare/src/index.ts
@@ -7,6 +7,9 @@ import { sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import glob from 'tiny-glob';
 
+export type { AdvancedRuntime } from './server.advanced';
+export type { DirectoryRuntime } from './server.directory';
+
 type Options = {
 	mode: 'directory' | 'advanced';
 };
diff --git a/packages/integrations/cloudflare/src/server.advanced.ts b/packages/integrations/cloudflare/src/server.advanced.ts
index 175756d6a..24358a5e0 100644
--- a/packages/integrations/cloudflare/src/server.advanced.ts
+++ b/packages/integrations/cloudflare/src/server.advanced.ts
@@ -12,7 +12,7 @@ type Env = {
 	name: string;
 };
 
-interface WorkerRuntime {
+export interface AdvancedRuntime {
 	runtime: {
 		waitUntil: (promise: Promise<any>) => void;
 		env: Env;
@@ -57,7 +57,7 @@ export function createExports(manifest: SSRManifest) {
 				},
 			});
 
-			const locals: WorkerRuntime = {
+			const locals: AdvancedRuntime = {
 				runtime: {
 					waitUntil: (promise: Promise<any>) => {
 						context.waitUntil(promise);
diff --git a/packages/integrations/cloudflare/src/server.directory.ts b/packages/integrations/cloudflare/src/server.directory.ts
index d4e4094de..64d820d99 100644
--- a/packages/integrations/cloudflare/src/server.directory.ts
+++ b/packages/integrations/cloudflare/src/server.directory.ts
@@ -7,7 +7,7 @@ if (!isNode) {
 	process.env = getProcessEnvProxy();
 }
 
-interface FunctionRuntime {
+export interface DirectoryRuntime {
 	runtime: {
 		waitUntil: (promise: Promise<any>) => void;
 		env: EventContext<unknown, string, unknown>['env'];
@@ -54,7 +54,7 @@ export function createExports(manifest: SSRManifest) {
 				cf: request.cf,
 			});
 
-			const locals: FunctionRuntime = {
+			const locals: DirectoryRuntime = {
 				runtime: {
 					waitUntil: (promise: Promise<any>) => {
 						context.waitUntil(promise);