docs: better documentation for runtime (#8190)

.changeset/silent-snakes-shave.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/cloudflare': patch
+---
+
+Improve documentation and export the types needed to type the `runtime` object.

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).

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';
 };

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);

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);