diff --git a/.changeset/silent-snakes-shave.md b/.changeset/silent-snakes-shave.md
new file mode 100644
index 000000000000..3f8c8c3ee7be
--- /dev/null
+++ b/.changeset/silent-snakes-shave.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/cloudflare': patch
+---
+
+Improve documentation and export the types needed to type the `runtime` object.
diff --git a/packages/integrations/cloudflare/README.md b/packages/integrations/cloudflare/README.md
index 61db6effc6ec..f5a939b29e2f 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
+///
+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
+///
+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 5f02184fab34..a0201008f9be 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 175756d6ab4a..24358a5e07d6 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) => void;
env: Env;
@@ -57,7 +57,7 @@ export function createExports(manifest: SSRManifest) {
},
});
- const locals: WorkerRuntime = {
+ const locals: AdvancedRuntime = {
runtime: {
waitUntil: (promise: Promise) => {
context.waitUntil(promise);
diff --git a/packages/integrations/cloudflare/src/server.directory.ts b/packages/integrations/cloudflare/src/server.directory.ts
index d4e4094de57e..64d820d999a7 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) => void;
env: EventContext['env'];
@@ -54,7 +54,7 @@ export function createExports(manifest: SSRManifest) {
cf: request.cf,
});
- const locals: FunctionRuntime = {
+ const locals: DirectoryRuntime = {
runtime: {
waitUntil: (promise: Promise) => {
context.waitUntil(promise);