You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit c9027eb
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/integrations/cloudflare.md
+34-18Lines changed: 34 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,7 @@ Void runs on Cloudflare Workers. This page covers how bindings work, how the plu
8
8
9
9
## Bindings
10
10
11
-
Void automatically infers and provisions Cloudflare bindings (D1, KV, R2) by scanning your source files. There are two ways to access them at runtime depending on your setup.
11
+
Void automatically infers and provisions Cloudflare bindings (D1, KV, R2, AI, Queues) by scanning your source files. There are two ways to access them at runtime depending on your setup.
When using framework mode (TanStack Start, React Router, SolidStart), the framework owns routing and you access bindings through the `cloudflare:workers` module instead:
42
42
43
+
::: warning ⚠️ Cloudflare env access in meta frameworks
44
+
Some frameworks, like Nuxt and SvelteKit, do not run in workerd during dev and therefore do not support directly importing from `cloudflare:workers`.
45
+
:::
46
+
43
47
```ts
44
48
import { env } from"cloudflare:workers";
45
49
@@ -77,40 +81,52 @@ Add `"void/env"` to your tsconfig `types` to get typed bindings on `env`:
77
81
}
78
82
```
79
83
80
-
This augments the `Cloudflare.Env` interface with `DB`, `KV`, and `STORAGE` and also pulls in `@cloudflare/workers-types`, so you don't need to add that separately.
84
+
This augments the `Cloudflare.Env` interface with `DB`, `KV`, `STORAGE`, `AI`, and `QUEUE_*` and also pulls in `@cloudflare/workers-types`, so you don't need to add that separately.
|`DB`|`D1Database`|`env.DB` / `c.env.DB` or `import from "void/db"`|
91
+
|`KV`|`KVNamespace`|`env.KV` / `c.env.KV` or `import from "void/kv"`|
92
+
|`STORAGE`|`R2Bucket`|`env.STORAGE` / `c.env.STORAGE` or `import from "void/storage"`|
93
+
|`AI`|`Ai`|`env.AI` / `c.env.AI` or `import from "void/ai"`|
94
+
|`QUEUE_*`|`Queue<T>`|`defineQueue()` or `import from "void/queue"`|
89
95
90
-
Bindings are [inferred automatically](../reference/resource-inference.md) by scanning your source files for these access patterns. You can also set them explicitly in `void.json`:
96
+
Bindings are [inferred automatically](../reference/resource-inference.md) by scanning your source files for import and access patterns. You can also set them explicitly in `void.json`:
`db`, `kv`, and `storage` accept a string to customize the binding name (e.g. `"db": "MY_DB"`). `ai` only accepts a boolean.
107
+
98
108
See [Configuration](../reference/config.md) for details.
99
109
100
110
### Wrangler passthrough
101
111
102
-
You can set non-binding wrangler fields like `compatibility_date`, `compatibility_flags`, and `vars` in `void.json`:
112
+
You can set non-binding wrangler fields like `compatibility_date`and `compatibility_flags` in `void.json`:
103
113
104
114
```json
105
115
{
106
116
"worker": {
107
-
"compatibility_date": "2025-12-01",
108
-
"compatibility_flags": ["nodejs_compat"],
109
-
"vars": { "API_URL": "https://api.example.com" }
117
+
"compatibility_date": "2026-02-12",
118
+
"compatibility_flags": ["nodejs_compat"]
110
119
}
111
120
}
112
121
```
113
122
123
+
For environment variables, use `.env` files instead of `worker.vars` — Void automatically loads `.env` files via Vite's `loadEnv` and merges them into the worker's `vars` bindings:
124
+
125
+
```bash
126
+
# .env
127
+
API_URL=https://api.example.com
128
+
```
129
+
114
130
Binding arrays (`d1_databases`, `kv_namespaces`, `r2_buckets`) are not allowed in the `worker` field — bindings are fully managed by Void. To use custom bindings with real resource IDs, add a `wrangler.jsonc` to your project root instead. See [Wrangler config merging](#wrangler-config-merging) for how Void handles this.
115
131
116
132
## Wrangler config merging
@@ -119,9 +135,9 @@ By default, Void configures the Cloudflare plugin entirely programmatically -- y
119
135
120
136
If you add a `wrangler.jsonc` (or `wrangler.json`) to your project root, Void respects it -- but **how** depends on whether Void owns the Cloudflare integration or a meta-framework does.
121
137
122
-
### Void-only mode, TanStack Start, and React Router
138
+
### Void-only modeand Vite-based frameworks
123
139
124
-
In Void's default mode and when using TanStack Start or React Router, Void controls the `@cloudflare/vite-plugin` directly. It passes a `config` callback that merges inferred bindings into whatever the plugin resolves from your `wrangler.jsonc`:
140
+
In Void's default mode and when using frameworks where Void controls the Cloudflare integration (TanStack Start, React Router), Void manages the `@cloudflare/vite-plugin` directly. It passes a `config` callback that merges inferred bindings into whatever the plugin resolves from your `wrangler.jsonc`:
125
141
126
142
1. The plugin reads your `wrangler.jsonc` and resolves it into a config object with `d1_databases`, `kv_namespaces`, `r2_buckets`, etc.
127
143
2. Void checks each inferred binding **by name** (e.g. `"DB"`, `"KV"`, `"STORAGE"`). If a binding with that name already exists in your config, it is left untouched.
@@ -134,9 +150,9 @@ Fields that Void always sets (`main`, `triggers`, `assets`) don't need to be in
134
150
135
151
In this mode, Void does **not** modify your `wrangler.jsonc` file on disk. The merge is purely in-memory.
When using SvelteKit, Nuxt, or Astro, the framework's own Cloudflare adapter owns the worker build and dev server. Void does **not** provide the `@cloudflare/vite-plugin`-- instead, it only contributes DB type codegen, migration management, and binding sync.
155
+
When using SvelteKit, Nuxt, or Astro, the framework's own Cloudflare adapter owns the worker build and dev server. Void does **not** provide the `@cloudflare/vite-plugin`— instead, it only contributes DB type codegen, migration management, and binding sync.
140
156
141
157
Because Void doesn't control the CF plugin in this mode, it can't merge bindings via a config callback. Instead, on dev startup Void syncs inferred bindings directly to your `wrangler.jsonc` file on disk:
142
158
@@ -218,7 +234,7 @@ Create `wrangler.jsonc` in your project root with the resource IDs from step 1:
You're also free to skip D1 entirely and connect to an external database like PostgreSQL or MySQL — see [External Databases](#external-databases) below.
10
10
11
+
::: warning ⚠️ Cloudflare env access in meta frameworks
12
+
Some frameworks, like Nuxt and SvelteKit, do not run in workerd during dev and therefore do not support directly importing from `cloudflare:workers`.
0 commit comments