how do I access Cloudflare bindings in my .astro files and .ts API routes?
#Cloudflare bindings
white cairn
sullen chasmBOT
Hi @white cairn. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
You can access Cloudflare bindings (including env vars, KV, Durable Objects, etc.) through the Cloudflare runtime that the @astrojs/cloudflare adapter exposes.
1. In .astro files (pages / components)
Use Astro.locals.runtime:
---
// Example: src/pages/index.astro
const { env } = Astro.locals.runtime;
// Access an env var or secret
const myVariable = env.MY_VARIABLE;
const secret = env.DB_PASSWORD;
// Access other bindings, e.g. KV, R2, etc.
// const kv = Astro.locals.runtime.MY_KV;
---
<html>
<body>
<p>Var: {myVariable}</p>
</body>
</html>
runtime contains all bindings defined in your wrangler.toml / wrangler.jsonc (e.g. vars, kv_namespaces, r2_buckets, etc.). [Cloudflare runtime]
2. In .ts / .js API routes
Use context.locals.runtime inside your endpoint handler:
// Example: src/pages/api/example.ts
export async function GET(context) {
const runtime = context.locals.runtime;
const { env } = runtime;
const value = env.MY_VARIABLE;
// const kv = runtime.MY_KV;
// const r2 = runtime.MY_BUCKET;
return new Response(`Value is: ${value}`);
}
3. Defining bindings
Bindings are configured in your Wrangler config, for example:
// wrangler.jsonc
{
"vars": {
"MY_VARIABLE": "test"
}
}
Secrets are added via npx wrangler secret put <KEY> and are also available on env through Astro.locals.runtime / context.locals.runtime. [Cloudflare runtime]
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
white cairn
@sullen chasm Property 'env' does not exist on type 'Runtime<Env>'.
This appears while using Astro.locals.runtime.env.SOUNDBOARD_R2
sullen chasmBOT
Let me check the knowledge base for you again. One moment! :books:
You’re running into a TypeScript typing issue, not a runtime one.
From the Cloudflare adapter docs, the runtime is typed via Runtime<Env>, and you’re expected to provide your own Env type that matches your Wrangler bindings. [Cloudflare typing]
By default, Runtime<Env> doesn’t know that env exists unless your Env type is wired in correctly. The docs show how to type runtime by extending App.Locals:
// src/env.d.ts
type Runtime = import('@astrojs/cloudflare').Runtime<Env>;
declare namespace App {
interface Locals extends Runtime {
otherLocals: {
test: string;
};
}
}
To fix your error:
- Define an
Envtype that includes your bindings, e.g.:
// src/env.d.ts
interface Env {
SOUNDBOARD_R2: R2Bucket; // or the correct type for your binding
// other bindings...
}
- Use that
EnvwithRuntime<Env>as in the example above.
Once Env is defined and wired into Runtime<Env>, Astro.locals.runtime.env.SOUNDBOARD_R2 will be correctly typed and the Property 'env' does not exist on type 'Runtime<Env>' error should disappear. [Cloudflare runtime; Cloudflare typing]
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
white cairn
@sullen chasm Now I'm getting this: Property 'runtime' does not exist on type 'Locals'.
sullen chasmBOT
Let me check the knowledge base for you again. One moment! :books:
That TypeScript error means your App.Locals type no longer includes the runtime properties that the Cloudflare adapter adds.
The Cloudflare docs show that you should extend App.Locals with the Runtime<Env> type, not replace it. [Cloudflare typing]
Your src/env.d.ts should look like this pattern:
// src/env.d.ts
// This Env type should match what `wrangler types` generates
// (or your own manual definition if you’re not using that).
interface Env {
// e.g. SOUNDBOARD_R2: R2Bucket;
// plus any other bindings...
}
type Runtime = import('@astrojs/cloudflare').Runtime<Env>;
declare namespace App {
// IMPORTANT: extend Locals with Runtime
interface Locals extends Runtime {
// you can add your own locals here too
// otherLocals?: { test: string };
}
}