void 0.21.9 → 0.23.0

package/skills/void/docs/guide/env-migration.md

@@ -2,7 +2,7 @@
 
 Use `.env` for local development and remote secrets for server-side production values.
 
-## 1. Preserve production values and consolidate local development values
+## 1. Back up and consolidate values
 
 Before changing any dotenv files, securely back up the production values you need to migrate outside the project directory. Keep them out of Git. Do not delete the original files until the upload and verification in step 3 succeed.
 
@@ -23,9 +23,9 @@ Ensure `.env` is ignored by Git:
 .env
 ```
 
-## 2. Remove masking modifiers
+## 2. Update `env.ts`
 
-Update `env.ts` before running any secret commands: they import the schema to validate values, and the removed modifiers cause that import to fail.
+Remove `.secret()` and `.public()` from `env.ts` before running secret commands.
 
 Change:
 
@@ -45,9 +45,9 @@ export default defineEnv({
 });
 ```
 
-Server storage is selected by the absence of the client prefix, not a modifier. Invalid input is redacted uniformly.
+Server keys have no `VITE_` prefix; client keys do.
 
-## 3. Move production server values remotely
+## 3. Upload server secrets
 
 For managed Void projects, upload each non-client schema key:
 
@@ -78,11 +78,11 @@ After the upload succeeds, confirm that all expected server names appear in the
 void secret list
 ```
 
-Remote stores return names only; plaintext values are validated during upload and again at worker startup. If an upload fails or a name is missing, retain the source values and retry before continuing.
+If an upload fails or a name is missing, keep the source values and retry before continuing.
 
 For direct Cloudflare deployments, remove the migrated server keys from `cloudflare.vars` in `void.config.ts` after confirming the upload. Void now treats any schema-declared server key in Worker `vars` as an error.
 
-## 4. Supply client values at build time
+## 4. Set client build values
 
 Move `VITE_*` production values to CI/build-shell variables, or make the value an explicit schema default:
 
@@ -92,13 +92,13 @@ export VITE_API_ORIGIN=https://api.example.com
 
 Keep these variables set for the remote check and deployment in step 5. Client values are compiled into browser assets and are public.
 
-The same public values are embedded in the server bundle for boot validation and `env.VITE_*` reads during server rendering. Do not upload them as remote secrets.
+These values are also available during server rendering. Do not upload them as remote secrets.
 
-## 5. Remove legacy files and verify
+## 5. Remove old files and verify
 
-Once the local values are in `.env`, the server values are uploaded and listed remotely, and the client values are available to the build, delete every `.env.*` file, `.env.example`, and `.dev.vars*` file from the project. Keep the secure backup until verification succeeds. Void's environment checks and deployment fail fast when they find a legacy file, rather than silently applying a precedence order.
+Once the local values are in `.env`, the server values are uploaded and listed remotely, and the client values are available to the build, delete every `.env.*` file, `.env.example`, and `.dev.vars*` file from the project. Keep the secure backup until verification succeeds. Environment checks and deployment reject these old files.
 
-`void env example` was removed because `.env.example` created a second dotenv source. Treat `env.ts` as the checked-in list of names, types, defaults, and requiredness.
+Use `env.ts` as the checked-in list of names, types, defaults, and requiredness. `void env example` is no longer supported.
 
 Then verify:
 

package/skills/void/docs/guide/env-vars.md

@@ -1,13 +1,6 @@
 # Environment variables
 
-Void uses one schema, one local dotenv file, and one production rule:
-
-- `env.ts` declares every application environment variable.
-- `.env` supplies local development values only. It is never deployed.
-- Production server values live in the platform's encrypted secret store.
-- Client-prefixed values are embedded at build time, so they are public by definition.
-
-This removes the distinction between “plain” and “secret-looking” server variables. Every server variable uses the same secure production path.
+Declare your environment variables in `env.ts`, then read them through `env` from `void/env`. Use `.env` for local values and `void secret put` for production server values.
 
 ## Define the schema
 
@@ -24,7 +17,7 @@ export default defineEnv({
 });
 ```
 
-Void generates `.void/env.d.ts`, validates values, and provides the typed `env` proxy:
+Import the typed `env` object in your app:
 
 ```ts
 import { env } from 'void/env';
@@ -46,7 +39,7 @@ STRIPE_KEY=sk_test_example
 VITE_API_ORIGIN=http://localhost:5173
 ```
 
-`.env` should be gitignored. Void rejects legacy `.env.local`, `.env.development`, `.env.production`, `.env.example`, other `.env.*` files, and Wrangler `.dev.vars*` files so there is no hidden precedence order.
+Keep `.env` out of Git. Other dotenv files, including `.env.local`, `.env.production`, `.env.example`, and Wrangler’s `.dev.vars*`, are not supported. See [Environment migration](./env-migration.md) if your app uses them.
 
 Run the local check at any time:
 
@@ -71,26 +64,17 @@ For bulk upload, prepare a dotenv-formatted file containing only production serv
 void secret sync production-secrets.txt
 ```
 
-`void secret put` and `void secret sync` validate the plaintext against `env.ts` before upload. The remote store encrypts the accepted value and only returns its name later, so subsequent deploy checks can prove presence but cannot re-read the plaintext. The worker validates the real value again at runtime.
+Secret commands validate values against `env.ts` before upload. Production values are encrypted and validated again at Worker startup.
 
 Client-prefixed keys are rejected by secret commands. Keep local development credentials and `VITE_*` values out of the production secrets file.
 
-`void deploy` never adds `.env` values to its manifest. It requires every required server key to exist remotely before upload.
-
-For direct Cloudflare deployment, select Cloudflare and use the same Void commands:
-
-```sh
-void connect --platform cloudflare
-void secret put DATABASE_URL
-void secret put STRIPE_KEY
-void deploy --platform cloudflare
-```
+`void deploy` requires every required server key to exist remotely. It never uploads `.env` values.
 
-Void stores the values as encrypted Worker secrets, emits the required server names through `secrets.required`, and refuses to deploy a schema-declared server key as a plaintext Worker `vars` entry.
+The same secret commands work for direct Cloudflare deployments. Schema-declared server values must be Worker secrets, not plaintext `vars`.
 
 ## Client values
 
-Keys beginning with `VITE_` are client values. This boundary is fixed, so the CLI, build, and secret commands always classify a name the same way even when a framework customizes Vite's own `envPrefix`.
+Keys beginning with `VITE_` are client values, even if your framework customizes Vite's `envPrefix`.
 
 Client values are embedded in browser JavaScript and are never secrets. Supply them through the build shell or use a schema default:
 
@@ -106,9 +90,7 @@ export default defineEnv({
 
 Builds ignore client values from `.env`; this prevents a developer's local value from silently becoming production configuration.
 
-The server bundle embeds those same public build values. Worker boot validation and server-side `env.VITE_*` reads use them without requiring remote secrets, keeping server rendering consistent with the browser. Server-only keys still come from runtime bindings and are validated at boot.
-
-Prerender path discovery can read route metadata without the deployed server secrets. Application requests, readiness checks, and actual page rendering still validate the runtime environment; a path generator that reads a required secret must have that value available.
+Server rendering uses the same public build values as the browser.
 
 ## Validation and redaction
 
@@ -120,11 +102,9 @@ void env types           # regenerate .void/env.d.ts
 
 Invalid-value diagnostics redact the supplied value by default. Set `VOID_ENV_UNMASK=1` only for deliberate local debugging; Void prints a notice when redaction is disabled.
 
-There are no `.secret()` or `.public()` schema modifiers. Storage now follows the server/client boundary, and diagnostics follow one redaction rule.
-
 ## Imports inside `env.ts`
 
-Void loads `env.ts` through Node's native `import()` before Vite transforms application code. Use relative imports or package names for schema helpers and shared constants. TypeScript path aliases and imports requiring custom Vite transforms are not supported in this file.
+Use relative imports or package names inside `env.ts`. TypeScript path aliases and imports that need Vite transforms are not supported.
 
 ## Migrating from the multi-file model
 

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

@@ -29,21 +29,6 @@ Deploy to [your own Cloudflare account](../integrations/cloudflare.md#deploy-to-
 
 [Static assets](./edge/static-assets) are cached at the edge. [Prerendering](./edge/prerendering) builds pages ahead of time, while [incremental revalidation](./edge/revalidation) caches pages rendered on demand. Database, storage, secrets, and deployment commands are available through Void.
 
-## How resource detection works
-
-```
-vite.config.ts                →  voidPlugin() (works with any Vite app)
-import { db }                 →  D1 database (auto-provisioned)
-import { kv }                 →  KV namespace (auto-provisioned)
-import { storage }            →  R2 bucket (auto-provisioned)
-import { ai }                 →  Workers AI inference (metered)
-db/schema.ts                  →  Drizzle schema (source of truth for DB types)
-db/migrations/*.sql           →  Applied to the selected database on deploy
-void deploy                   →  Deploy to the saved Cloudflare or Void target
-```
-
-The Vite plugin detects supported imports and adds the corresponding bindings. Void also detects your [app type](./app-types) to choose the build and deployment flow. Use `void.config.ts` when you need to control either choice.
-
 ## Next steps
 
 - [Quickstart](./quickstart): get a running app in minutes

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

@@ -45,22 +45,9 @@ export default defineScheduled(async (controller, env) => {
 
 ## `defineScheduled`
 
-Wrap a handler with `defineScheduled()` to get types for the scheduled event, environment, and execution context.
+Wrap a handler with [`defineScheduled()`](../reference/api/handlers.md#definescheduled-handler) to type its scheduled event, environment, and execution context.
 
-Handler signature:
-
-```ts
-(controller: ScheduledController, env: CloudEnv['Bindings'], ctx: ExecutionContext) =>
-  unknown | Promise<unknown>;
-```
-
-Notes:
-
-- Jobs are matched by exact cron string.
-- When jobs share an expression, each matching job runs once per invocation. Void waits for all matching jobs, even if one fails, then reports any failures. Native triggers and managed deliveries are deduplicated by expression.
-- Job modules are lazy-loaded at runtime.
-- Files or directories starting with `_` are ignored.
-- Missing `cron` export causes an error during scan/build.
+Jobs sharing a cron expression each run once per invocation. Void waits for all matching jobs and reports any failures. Files and directories starting with `_` are ignored.
 
 ## Local development
 
@@ -72,7 +59,7 @@ Content-Type: application/json
 { "cron": "<expression>", "scheduledTime": <unix_ms> }
 ```
 
-The `cron` value must match a string you exported from a `crons/*.ts` file — that's how the dispatcher routes to the right handler. Returns `{ "ok": true }` on success.
+Set `cron` to an expression exported by your job. A successful call returns `{ "ok": true }`.
 
 The endpoint requires a local dev trigger token. Void prints a paste-ready curl command with the current token when the dev server starts.
 
@@ -89,6 +76,4 @@ The endpoint works in native Void apps and supported frameworks. Framework jobs
 
 ## Deployment behavior
 
-On deploy, Void includes all discovered job schedules in the deploy manifest and configures worker cron triggers automatically.
-
 Native scheduled events do not require a manual HTTP token. For framework deployments, HTTP requests to `/__void/scheduled` require a matching `x-void-internal` token: the managed platform supplies its proxy token, or you can explicitly configure `CRON_SECRET` for manual calls. An absent or mismatched token returns `401` without running a job.

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

@@ -4,7 +4,7 @@ outline: deep
 
 # Key-Value Storage
 
-Void provides a typed KV client with automatic JSON serialization for [Cloudflare Workers KV](https://developers.cloudflare.com/kv/). Import `kv` from `void/kv` and start reading and writing data.
+Read and write data in [Cloudflare Workers KV](https://developers.cloudflare.com/kv/) with `kv` from `void/kv`. Values are stored as JSON, and `kv.map()` gives a collection its own key prefix and value type.
 
 ## Basic Operations
 
@@ -25,7 +25,9 @@ Values are automatically parsed as JSON. If the stored value isn't valid JSON, t
 await kv.put('user:123', { name: 'Alice', role: 'admin' });
 ```
 
-Objects are automatically JSON-stringified. Strings are stored as-is.
+Values, including strings, are JSON-serialized. Reads preserve their types, so a string such as `"123"` or `"null"` comes back as a string.
+
+If an older Void version stored a JSON-looking string as raw text, rewrite that key with `kv.put(key, originalString)`. Existing stored values keep their previous read behavior; Void cannot distinguish an old raw string such as `"123"` from a stored number. Use the original string or read its raw text through `c.env.KV.get(key)` when rewriting it.
 
 Add a TTL (in seconds) or absolute expiration (Unix timestamp):
 
@@ -96,12 +98,4 @@ const result = await sessions.list();
 
 Maps have the same methods as the base client (`get`, `put`, `delete`, `list`, `getWithMetadata`) but with a typed value and automatic prefixing.
 
-## How It Works
-
-The KV client is a thin wrapper over the Cloudflare KV API that adds two things:
-
-1. **Auto serialization:** `put()` calls `JSON.stringify()` on non-string values. `get()` calls `JSON.parse()` with a fallback to the raw string for values that are not JSON. You can store and retrieve objects without manual serialization.
-
-2. **Typed maps:** `kv.map<T>(prefix)` returns a scoped client where all keys are prefixed with `"prefix:"` and values are typed as `T`. This is useful for organizing related data such as sessions, cache entries, and feature flags without manually managing prefixes.
-
-> **Escape hatch:** The `kv` client covers the most common KV operations. For advanced use cases like `getWithMetadata` with specific cache behaviors, you can access the raw `KVNamespace` binding via `c.env.KV` in a route handler.
+For operations beyond this client, access the raw `KVNamespace` through `c.env.KV` in a route handler.

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

@@ -71,11 +71,7 @@ await unsubscribePost();
 stream.close();
 ```
 
-The helper opens one native `EventSource`, waits for it to open, then sends
-batched `POST` control operations. Subscription ids are scoped to the
-connection. Reusing an id replaces the previous subscription with that id. If
-the transport drops, the helper reconnects and resubmits active subscriptions
-with their latest `eventId` as `lastEventId`.
+Subscription IDs are scoped to a connection. Reusing an ID replaces its subscription. After reconnecting, the helper restores active subscriptions and sends their latest `eventId` as `lastEventId`.
 
 ## Publish
 
@@ -101,19 +97,7 @@ await live.withEnv(env).publish('post:12', { title: 'Updated title' });
 
 ## Authorization
 
-Every live connection has an owner. The owner is the identity allowed to send
-control operations for that SSE connection. `connect()` resolves and stores the
-owner; `control()` resolves the owner again and rejects the request if it does
-not match.
-
-The quickstart uses an anonymous stream:
-
-```ts
-export const live = defineLiveStream({
-  id: 'app',
-  allowAnonymousControl: true,
-});
-```
+Only a connection's owner can change its subscriptions. The example above allows anonymous connections; authenticated streams use the current Void user by default.
 
 For authenticated streams, pass the same owner key to `connect()` and
 `control()`:
@@ -136,13 +120,6 @@ export const live = defineLiveStream({
 });
 ```
 
-Then the route handlers can stay thin:
-
-```ts
-export const GET = defineHandler((c) => live.connect(c));
-export const POST = defineHandler((c) => live.control(c));
-```
-
 When `identifyConnection` returns `null` or `undefined`, Void falls back to the
 current authenticated user and uses `user:${user.id}` when the user has a string
 `id`. If neither path produces an owner and `allowAnonymousControl` is not set,
@@ -172,25 +149,7 @@ export const live = defineLiveStream({
 - `100` queued events per connection
 - `64 KiB` per encoded event envelope
 
-A topic is the unit of fanout. For example, if each blog post uses a topic like
-`post:${postId}`, then each post can have up to `256` active live subscribers at
-one time. Other posts use separate topics and have separate limits.
-
-Streams can have many possible topics. Topics are created on demand when clients
-subscribe or publishers send events, so an app with thousands of posts, rooms, or
-documents can use one topic per entity without provisioning them ahead of time.
-The limit applies to each active topic, not to the total number of topic names
-your app might use.
-
-For example, a blog with `10,000` posts can model its live capacity as
-`10,000 posts × up to 256 active subscribers per post topic`.
-
-That shape works because each post topic is independent. A single post with more
-than `256` active live subscribers would need a larger broadcast design.
-
-These limits apply to live subscriptions, not total users or total page views.
-One user with two open tabs may count twice. Disconnected subscriptions are
-pruned, but they can count until the runtime observes that they are stale.
+Each active topic supports up to 256 subscriptions, regardless of how many topic names your app uses. For example, `post:${postId}` gives each post its own subscriber limit. A user with two open tabs can count twice.
 
 You can lower limits per stream:
 
@@ -207,16 +166,6 @@ export const live = defineLiveStream({
 
 ## Delivery Semantics
 
-Live delivery is at most once: clients may miss events, and Void doesn't replay them automatically.
-
-- one SSE connection can hold many topic subscriptions
-- publish cost is proportional to subscribers of the topic
-- events are ordered within one topic
-- clients using the raw HTTP protocol must resubscribe after reconnect
-- deploys, rollbacks, Worker restarts, browser reconnects, and network changes
-  can drop live state
-- your app handles replay, cache invalidation, live queries, and client state
+Events are ordered within a topic and delivered at most once. Deploys, rollbacks, restarts, and reconnects can drop live state, so clients may miss events. Raw HTTP clients must resubscribe after reconnecting.
 
-Use an application database, queue, or custom Durable Object for replay. Use
-`eventId` and caller-provided `lastEventId` values as application protocol
-fields when you build that layer.
+For replay, store events in your application and use `eventId` and `lastEventId` to resume. Void does not store events or manage client state.