void 0.7.13 → 0.8.1

package/dist/{yarn-pnp-6LD6_3Ej.mjs → yarn-pnp-QgEYVC3V.mjs}

@@ -1,4 +1,4 @@
-import { a as join, n as dirname } from "./pathe.M-eThtNZ-D-kmWkCS.mjs";
+import { a as join, n as dirname } from "./pathe.M-eThtNZ-BrPhGF_K.mjs";
 import { existsSync, readdirSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 //#region src/cli/yarn-pnp.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "void",
-  "version": "0.7.13",
+  "version": "0.8.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/voidzero-dev/void.git",
@@ -48,6 +48,7 @@
       "import": "./dist/index.mjs",
       "require": "./dist/index.mjs"
     },
+    "./schema.json": "./schema.json",
     "./handler": {
       "types": "./dist/runtime/handler.d.mts",
       "import": "./dist/runtime/handler.mjs",
@@ -332,7 +333,7 @@
     "valibot": ">=1.0.0-beta.7",
     "vite": "^8.0.0",
     "zod": "^3.25.0 || ^4.0.0",
-    "@void/md": "0.7.13"
+    "@void/md": "0.8.1"
   },
   "peerDependenciesMeta": {
     "@void/md": {

package/schema.json

@@ -8,6 +8,11 @@
       "type": "string",
       "description": "JSON Schema URL for IDE support"
     },
+    "sourceDir": {
+      "type": "string",
+      "pattern": "^(?!/)(?!\\.\\.?$)(?!\\./$)(?!\\.\\./)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\s$)(?!\\s).+$",
+      "description": "Directory containing Void source conventions such as pages, routes, middleware, crons, queues, db, auth.ts, and env.ts. Omit to use the project root."
+    },
     "target": {
       "type": "string",
       "enum": ["cloudflare", "node", "bun", "deno"],

package/skills/void/docs/guide/ai.md

@@ -208,7 +208,7 @@ All [AI Gateway providers](https://developers.cloudflare.com/ai-gateway/usage/pr
 For production, add your API key as a project secret:
 
 ```bash
-void secrets set OPENAI_API_KEY sk-...
+void secret put OPENAI_API_KEY=sk-...
 ```
 
 For local development, add it to `.env.local` in your project root:

package/skills/void/docs/guide/app-types.md

@@ -50,7 +50,7 @@ Void supports deploying Vite-based meta-framework apps with `void deploy`. The f
 | [Analog](https://analogjs.org/)                     | `@analogjs/platform`    | [Guide](../integrations/frameworks/analog.md)         |
 | [Astro](https://astro.build/)                       | `astro`                 | [Guide](../integrations/frameworks/astro.md)          |
 
-Add `voidPlugin()` to the framework's Vite config to get binding inference, typed DB generation, migration management, auth, cron jobs, queues, and caching. See the [Meta Frameworks Integration](../integrations/frameworks/overview.md) for the full feature matrix, deploy pipeline, and per-framework setup guides.
+Add `voidPlugin()` to the framework's Vite config to get binding inference, typed DB generation, migration management, cron jobs, queues, and caching. Void-managed auth is not supported in framework mode; use Better Auth's official integration for your framework. See the [Meta Frameworks Integration](../integrations/frameworks/overview.md) for the full feature matrix, deploy pipeline, and per-framework setup guides.
 
 **Deploy:** `void deploy` runs the framework build, packages the output, and deploys to Void. The framework still owns routing and SSR, while Void handles resource provisioning, migrations, and edge hosting.
 

package/skills/void/docs/guide/database/postgresql.md

@@ -29,10 +29,10 @@ Add to your `void.json`:
 For local development, add `DATABASE_URL` to `.env.local`:
 
 ```
-DATABASE_URL=postgres://user:password@host:5432/mydb
+DATABASE_URL=postgresql://user:password@host:5432/mydb?sslmode=require
 ```
 
-This connects directly to your Postgres database during `void dev`.
+This connects directly to your Postgres database during local Vite development.
 
 ### 3. Deploy
 
@@ -40,10 +40,11 @@ On your first deploy, the CLI will prompt for your connection string:
 
 ```
 Your project uses PostgreSQL. Enter your connection string:
-> postgres://user:password@host:5432/mydb
+> postgresql://user:password@host:5432/mydb?sslmode=require
 ```
 
 Void provisions a Hyperdrive configuration and stores only the config ID. Your connection string is sent directly to Cloudflare's API and is never stored by Void.
+Both `postgres://` and `postgresql://` URLs are supported, including provider-supplied query strings such as `?sslmode=require`.
 
 You can also set the connection string ahead of time with `void db set-url`.
 

package/skills/void/docs/guide/edge/headers.md

@@ -74,6 +74,6 @@ No configuration is needed. If the framework generates a `_headers` file, it is
 
 1. `void deploy` reads header rules from the framework `_headers` file (if present) and `routing.headers` in `void.json`, then includes them in the deploy manifest.
 2. The platform stores the rules in the KV routing entry for your project.
-3. The dispatch worker applies matching rules to static responses before edge caching.
+3. The dispatch worker applies matching rules to matching responses before returning them. Cacheable responses are cached with the final headers.
 
 Because rules are evaluated at the edge, there is no extra latency cost. Headers are applied inline before the response is returned and cached.

package/skills/void/docs/guide/edge/static-assets.md

@@ -67,6 +67,40 @@ This happens automatically for all static assets. No configuration is needed.
 
 You can override caching headers or add your own for any static asset path using [Custom Headers](./headers).
 
+## Request pipeline
+
+Static assets can run in front of the worker, behind the worker, or without any worker at all. Void chooses the pipeline from the app shape so static pages stay static unless application code must inspect document navigations.
+
+### Deploy shapes
+
+| Shape                                                                                   | Worker deployed | First handler for assets | First handler for document navigations | Miss behavior                                                                                                          |
+| --------------------------------------------------------------------------------------- | --------------- | ------------------------ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `inference.appType: "static"`                                                           | No              | Asset platform           | Asset platform                         | Platform 404 page.                                                                                                     |
+| Static SPA deploy                                                                       | No              | Asset platform           | Asset platform                         | Platform serves `/index.html` for unmatched navigations. If user `routing.fallbacks` exist, Void ships fallback rules. |
+| Void app with only `/api` routes                                                        | Yes             | Asset platform           | Asset platform                         | Static navigations keep the platform SPA fallback; API asset misses fall through to the worker route table.            |
+| Void app with `middleware/`, managed auth, non-`/api` routes, WebSockets, live bindings | Yes             | Worker first             | Worker first                           | Asset misses stay 404, then the worker serves `/index.html` for HTML requests after routes and middleware run.         |
+| Pages, SSR, and framework apps                                                          | Yes             | Worker first             | Worker first                           | Asset misses stay 404. Pages, SSR, or framework rendering owns HTML responses, including intentional HTML 404s.        |
+
+### Worker-first Void apps
+
+For worker-owned HTML, Void sets Cloudflare assets to `not_found_handling: "none"` and configures `run_worker_first`. The request order is:
+
+1. Platform routing rules that always run before assets, such as redirects and forced rewrites.
+2. Worker route table, middleware, auth, WebSocket upgrades, Pages, or SSR.
+3. `env.ASSETS.fetch()` from inside the worker for static files.
+4. For non-Pages, non-SSR Void apps only, a worker-side SPA fallback to `/index.html` when the original request accepts HTML.
+5. The worker's original 404.
+
+This is the path needed for preview auth and other middleware. Cloudflare's platform SPA fallback can serve `index.html` directly for browser navigations; when that happens, middleware never sees the request. Worker-owned HTML avoids that by moving fallback HTML behind middleware.
+
+### Asset-first Void apps
+
+For Void apps with only `/api` routes, Void does not enable `run_worker_first`. Static assets and SPA navigations stay on the asset platform. Requests that do not resolve to an asset and are not handled by the platform SPA fallback, such as `/api/hello`, fall through to the worker.
+
+### Generated config
+
+Void owns the generated asset routing policy during dev and build. If a root `wrangler.jsonc` contains stale `not_found_handling` or `run_worker_first` values, Void replaces those fields so generated config cannot accidentally change which layer sees a request first.
+
 ## API routes and SSR pages
 
 API responses (`/api/*`) and SSR-rendered pages without file extensions always hit the worker. They are **not** edge-cached by the dispatch layer.

package/skills/void/docs/guide/sandboxes.md

@@ -12,7 +12,7 @@ import { getSandbox } from 'void/sandbox';
 
 export const POST = defineHandler(async (c) => {
   const { command } = await c.req.json<{ command: string }>();
-  const sandbox = getSandbox('default');
+  const sandbox = await getSandbox('default');
   const result = await sandbox.exec(command);
 
   return c.json(result);
@@ -58,7 +58,8 @@ Available fields:
 ```ts
 import { getSandbox } from 'void/sandbox';
 
-const sandbox = getSandbox(`user-${user.id}`);
+// inside an async handler
+const sandbox = await getSandbox(`user-${user.id}`);
 await sandbox.writeFile('/tmp/input.txt', 'hello');
 const result = await sandbox.exec('cat /tmp/input.txt');
 ```

package/skills/void/docs/guide/ssr.md

@@ -10,6 +10,28 @@ Void supports framework-agnostic SSR via explicit server and client entries. Thi
 For most apps, [Pages Routing](./pages-routing/overview) handles SSR automatically. You do not need entry files or hydration code.
 :::
 
+## Relationship to Pages Routing
+
+Custom SSR is separate from Pages Routing. Use Custom SSR when you want to bring
+your own root component, router, data loading, HTML shell, and hydration logic.
+
+The `App` component in the examples below is not a Void convention and it is not
+the same thing as `pages/layout.tsx`. It is just the root component for your
+custom-rendered application:
+
+```tsx
+// src/App.tsx
+export default function App({ url }: { url: string }) {
+  return url === '/about' ? <main>About</main> : <main>Home</main>;
+}
+```
+
+If you are using `pages/` with `@void/react`, `@void/vue`, `@void/svelte`, or
+`@void/solid`, do not create `src/main.ssr.*`, `src/main.client.*`, or
+`src/App.*` for Pages mode. The adapter generates the SSR and hydration entries
+and automatically composes your `pages/layout.*`, route components, loaders, and
+actions.
+
 ## Required entries
 
 SSR mode is enabled when both of these exist:
@@ -40,8 +62,9 @@ The recommended form is `defineRender(...)` for inferred types.
 
 ```ts
 {
-  head: string; // styles/modulepreload/Vite client+preamble (dev)
-  body: string; // main client entry script tag
+  css: string; // stylesheet links for <head>
+  preloads: string; // modulepreload/Vite client+preamble tags for <head>
+  body: string; // main client entry script tag before </body>
 }
 ```
 

package/skills/void/docs/integrations/cloudflare.md

@@ -38,7 +38,7 @@ export const GET = defineHandler(async (c) => {
 
 ### Via `cloudflare:workers` import
 
-When using framework mode (TanStack Start, React Router, SolidStart), the framework owns routing and you access bindings through the `cloudflare:workers` module instead:
+When using framework mode (TanStack Start or React Router), the framework owns routing and you access bindings through the `cloudflare:workers` module instead:
 
 ::: warning ⚠️ Cloudflare env access in meta frameworks
 Some frameworks, like Nuxt and SvelteKit, do not run in workerd during dev and therefore do not support directly importing from `cloudflare:workers`.
@@ -91,7 +91,7 @@ This augments the `Cloudflare.Env` interface with `DB`, `KV`, `STORAGE`, `AI`, a
 | `KV`      | `KVNamespace` | `env.KV` / `c.env.KV` or `import from "void/kv"`                |
 | `STORAGE` | `R2Bucket`    | `env.STORAGE` / `c.env.STORAGE` or `import from "void/storage"` |
 | `AI`      | `Ai`          | `env.AI` / `c.env.AI` or `import from "void/ai"`                |
-| `QUEUE_*` | `Queue<T>`    | `defineQueue()` or `import from "void/queue"`                   |
+| `QUEUE_*` | `Queue<T>`    | `defineQueue()` or `import { queues } from "void/queues"`       |
 
 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`:
 
@@ -120,7 +120,7 @@ You can set non-binding wrangler fields like `compatibility_date` and `compatibi
 }
 ```
 
-For environment variables, use `.env` files instead of `worker.vars`. Void automatically loads `.env` files through Vite's `loadEnv` and merges them into the worker's `vars` bindings:
+For environment variables, use `.env` files for local values and secrets. Void automatically loads `.env` files through Vite's `loadEnv` and merges them into the worker's `vars` bindings:
 
 ```bash
 # .env
@@ -129,6 +129,8 @@ API_URL=https://api.example.com
 
 Binding arrays such as `d1_databases`, `kv_namespaces`, and `r2_buckets` are not allowed in the `worker` field because Void manages bindings for you. If you need custom bindings with real resource IDs, add a `wrangler.jsonc` to the project root instead. See [Wrangler config merging](#wrangler-config-merging) for details.
 
+For non-secret plain-text defaults, you can also set `worker.vars` in `void.json`. Values from `.env` files override `worker.vars`.
+
 ## Wrangler config merging
 
 By default, Void configures the Cloudflare plugin programmatically, so you don't need a `wrangler.jsonc` for bindings. Void pins a Workers compatibility date in `void.json` `worker.compatibility_date`; if no date is already configured in `void.json` or `wrangler.jsonc`/`wrangler.json`, Void writes the latest known-good date to `void.json`. Bindings are inferred from your source code and provisioned with local placeholder IDs for development.

package/skills/void/docs/integrations/frameworks/overview.md

@@ -57,7 +57,7 @@ Most configuration is inferred automatically. Use `void.json` to override defaul
 
 ```json
 {
-  "$schema": "https://unpkg.com/void/schema.json",
+  "$schema": "./node_modules/void/schema.json",
   "inference": {
     "build": "nuxt build",
     "scanDirs": ["src", "server", "lib"],

package/skills/void/docs/integrations/nodejs-bun-deno.md

@@ -106,18 +106,19 @@ These Void features work identically across all targets:
 
 The following imports are **not available** with a non-CF target and produce a compile-time error:
 
-| Import         | CF Feature                   |
-| -------------- | ---------------------------- |
-| `void/db`      | D1 (SQL database)            |
-| `void/kv`      | KV (key-value storage)       |
-| `void/storage` | R2 (blob storage)            |
-| `void/auth`    | Void-managed Better Auth     |
-| `void/ai`      | Workers AI                   |
-| `void/env`     | CF env type augmentation     |
-| `void/ws`      | Durable Objects + WebSockets |
+| Import         | CF Feature               |
+| -------------- | ------------------------ |
+| `void/db`      | D1 (SQL database)        |
+| `void/kv`      | KV (key-value storage)   |
+| `void/storage` | R2 (blob storage)        |
+| `void/auth`    | Void-managed Better Auth |
+| `void/ai`      | Workers AI               |
+| `void/env`     | CF env type augmentation |
 
 If you need a database or storage, use an external provider and connect via standard Node.js libraries.
 
+Void-managed WebSocket route files (`*.ws.ts`) are still Cloudflare-only because they compile to Durable Objects. The `void/ws` subpath is not compile-time blocked on non-CF targets, so browser-side `connect()` code can still be bundled when a WebSocket runtime is available.
+
 ### No cron job runtime
 
 You can still define [cron jobs](../guide/jobs.md) in `crons/` and they will compile into the bundle, but there is no built-in scheduler to invoke them. On Cloudflare, Workers Cron Triggers call the `scheduled` handler automatically. On Node.js, you'll need an external scheduler (e.g. `node-cron`, systemd timers, or your hosting platform's cron) to trigger the exported handler.