devflare 1.0.0-next.10 → 1.0.0-next.11

package/LLM.md

@@ -64,7 +64,8 @@ The classic mixups are:
 
 - `files.routes` vs top-level `routes`
 - `vars` vs `secrets`
-- Bun `.env` loading vs runtime secret loading
+- Bun or host `.env*` loading vs runtime secret loading
+- config-time `.env*` files vs local runtime `.dev.vars*` files
 - Devflare `config.env` overrides vs Wrangler environment blocks
 - main-entry `env` vs runtime `env`
 
@@ -110,6 +111,11 @@ Core public capabilities today:
 
 Devflare is not a replacement runtime. It is a higher-level developer system that sits on top of the Cloudflare ecosystem.
 
+The shortest truthful mental model is:
+
+- **Vite** is the optional outer app/framework host. Devflare plugs into it only when the current package has a local `vite.config.*`.
+- **Rolldown** is the inner builder Devflare uses when Devflare itself needs to transform Worker source into runnable Worker modules. Today that shows up most clearly in the Durable Object bundler and its watch/rebuild loop.
+
 ### Authoring model
 
 A **surface** is a distinct handler or entry file that Devflare treats as its own concern. The common surfaces are:
@@ -525,9 +531,234 @@ Secondary keys:
 | `limits` | worker limits |
 | `wsRoutes` | local WebSocket proxy rules for dev |
 | `vite` | Devflare Vite metadata |
-| `rolldown` | worker-only bundler options |
+| `rolldown` | Durable Object bundler options |
 | `wrangler.passthrough` | raw Wrangler overrides after compile |
 
+### Complete config property reference
+
+Treat this as the exhaustive property checklist for `defineConfig({...})`. The later sections explain behavior in narrative form; this section answers “what keys exist right now, what shape do they accept, and what do they control?”
+
+#### Root properties
+
+| Property | Shape | Required | Current behavior |
+|---|---|---|---|
+| `name` | `string` | yes | Worker name compiled to Wrangler `name`. It is also the base name used for generated auxiliary DO workers (`${name}-do`) when Devflare creates one. |
+| `accountId` | `string` | no | Compiled to Wrangler `account_id`. Most relevant for deploy flows and remote-oriented bindings such as AI and Vectorize. Not currently supported inside `config.env`. |
+| `compatibilityDate` | `string` (`YYYY-MM-DD`) | no | Compiled to Wrangler `compatibility_date`. Defaults to the current date when omitted. |
+| `compatibilityFlags` | `string[]` | no | Additional Workers compatibility flags. Devflare also forces `nodejs_compat` and `nodejs_als`. |
+| `files` | object | no | Explicit surface file paths and discovery globs. Use this when a surface matters to generated output. |
+| `bindings` | object | no | Cloudflare binding declarations. These compile to Wrangler binding sections and also drive generated typing. |
+| `triggers` | object | no | Scheduled trigger configuration such as cron expressions. |
+| `vars` | `Record<string, string>` | no | Non-secret runtime bindings compiled into Wrangler `vars`. |
+| `secrets` | `Record<string, { required?: boolean }>` | no | Secret declarations only. Values do not live here. |
+| `routes` | `Array<{ pattern; zone_name?; zone_id?; custom_domain? }>` | no | Cloudflare deployment routes. This is separate from the built-in file router. |
+| `wsRoutes` | `Array<{ pattern; doNamespace; idParam?; forwardPath? }>` | no | Dev-only WebSocket proxy rules that forward matching upgrade requests to Durable Objects. Not compiled into Wrangler config. |
+| `assets` | `{ directory: string; binding?: string }` | no | Static asset directory config compiled into Wrangler `assets`. |
+| `limits` | `{ cpu_ms?: number }` | no | Worker execution limits compiled into Wrangler `limits`. |
+| `observability` | `{ enabled?: boolean; head_sampling_rate?: number }` | no | Workers observability and sampling config compiled into Wrangler `observability`. |
+| `migrations` | `Migration[]` | no | Durable Object migration history compiled into Wrangler `migrations`. |
+| `rolldown` | object | no | Rolldown builder configuration for Devflare's own code-transformation path, currently focused on Durable Object workers. This is not a replacement for `vite.config.*`. |
+| `vite` | object | no | Devflare-owned Vite metadata namespace. Raw Vite server/build/resolve config still belongs in local `vite.config.*`. |
+| `env` | `Record<string, EnvOverride>` | no | Named environment overlays merged into the base config before compile/build/deploy. |
+| `wrangler` | `{ passthrough?: Record<string, unknown> }` | no | Escape hatch for unsupported Wrangler keys, merged after native Devflare compile. |
+| `build` | object | legacy | Deprecated alias normalized into `rolldown`. Keep accepting it for compatibility; teach `rolldown` in new docs. |
+| `plugins` | `unknown[]` | legacy | Deprecated alias normalized into `vite.plugins`. Raw Vite plugin wiring still belongs in `vite.config.*`. |
+
+#### `files`
+
+`files` is where Devflare discovers or pins the files that make up your worker surfaces.
+
+| Key | Shape | Default or convention | Meaning |
+|---|---|---|---|
+| `fetch` | `string \| false` | `src/fetch.ts` when present | Main HTTP entry. Keep this explicit when build or deploy output depends on it. |
+| `queue` | `string \| false` | `src/queue.ts` when present | Queue consumer surface. |
+| `scheduled` | `string \| false` | `src/scheduled.ts` when present | Scheduled/cron surface. |
+| `email` | `string \| false` | `src/email.ts` when present | Inbound email surface. |
+| `durableObjects` | `string \| false` | `**/do.*.{ts,js}` | Discovery glob for Durable Object classes. Respects `.gitignore`. |
+| `entrypoints` | `string \| false` | `**/ep.*.{ts,js}` | Discovery glob for `WorkerEntrypoint` classes. Respects `.gitignore`. |
+| `workflows` | `string \| false` | `**/wf.*.{ts,js}` | Discovery glob for workflow classes. Respects `.gitignore`. |
+| `routes` | `{ dir: string; prefix?: string } \| false` | `src/routes` when that directory exists | Built-in route-tree config. `dir` changes the route root; `prefix` mounts it under a static pathname prefix such as `/api`; `false` disables route discovery. |
+| `transport` | `string \| null` | `src/transport.{ts,js,mts,mjs}` when present | Custom serialization transport file. The file must export a named `transport` object. Set `null` to disable autodiscovery explicitly. |
+
+Current `files` rules worth keeping explicit:
+
+- `compileConfig()` only writes Wrangler `main` when `files.fetch` is explicit
+- higher-level `build`, `deploy`, and `devflare/vite` flows may still generate a composed `.devflare/worker-entrypoints/main.ts` when multiple surfaces must be stitched together
+- `wrangler.passthrough.main` opts out of that composed-entry generation path
+- `createTestContext()` and local dev can still auto-discover conventional files even when you omit them from config
+
+#### `bindings`
+
+`bindings` groups Cloudflare service bindings by kind.
+
+| Key | Shape | Meaning |
+|---|---|---|
+| `kv` | `Record<string, string>` | KV namespace binding name → namespace id |
+| `d1` | `Record<string, string>` | D1 binding name → database id |
+| `r2` | `Record<string, string>` | R2 binding name → bucket name |
+| `durableObjects` | `Record<string, string \| { className: string; scriptName?: string }>` | Durable Object namespace binding. String form is shorthand for `{ className }`. Object form also covers cross-worker DOs and `ref()`-driven bindings. |
+| `queues` | `{ producers?: Record<string, string>; consumers?: QueueConsumer[] }` | Queue producer bindings plus consumer settings |
+| `services` | `Record<string, { service: string; environment?: string; entrypoint?: string }>` | Worker service bindings. `ref().worker` and `ref().worker('Entrypoint')` normalize here. |
+| `ai` | `{ binding: string }` | Workers AI binding |
+| `vectorize` | `Record<string, { indexName: string }>` | Vectorize index bindings |
+| `hyperdrive` | `Record<string, { id: string }>` | Hyperdrive bindings |
+| `browser` | `{ binding: string }` | Browser Rendering binding |
+| `analyticsEngine` | `Record<string, { dataset: string }>` | Analytics Engine dataset bindings |
+| `sendEmail` | `Record<string, { destinationAddress?: string; allowedDestinationAddresses?: string[]; allowedSenderAddresses?: string[] }>` | Outbound email bindings |
+
+Queue consumer objects currently support:
+
+| Field | Shape | Meaning |
+|---|---|---|
+| `queue` | `string` | Queue name to consume |
+| `maxBatchSize` | `number` | Max messages per batch |
+| `maxBatchTimeout` | `number` | Max seconds to wait for a batch |
+| `maxRetries` | `number` | Max retry attempts |
+| `deadLetterQueue` | `string` | Queue for permanently failed messages |
+| `maxConcurrency` | `number` | Max concurrent batch invocations |
+| `retryDelay` | `number` | Delay between retries in seconds |
+
+Two `bindings` details that matter in practice:
+
+- `bindings.sendEmail` must use either `destinationAddress` or `allowedDestinationAddresses`, not both
+- `bindings.durableObjects.*.scriptName` is how you point a binding at another worker when the class does not live in the main worker bundle
+
+#### `triggers`, `routes`, and `wsRoutes`
+
+| Property | Shape | Current behavior |
+|---|---|---|
+| `triggers.crons` | `string[]` | Cloudflare cron expressions compiled into Wrangler `triggers.crons` |
+| `routes[].pattern` | `string` | Deployment route pattern such as `example.com/*` |
+| `routes[].zone_name` | `string` | Optional zone association |
+| `routes[].zone_id` | `string` | Optional zone association alternative to `zone_name` |
+| `routes[].custom_domain` | `boolean` | Mark route as a custom domain |
+| `wsRoutes[].pattern` | `string` | Local URL pattern to intercept for WebSocket upgrades |
+| `wsRoutes[].doNamespace` | `string` | Target Durable Object namespace binding name |
+| `wsRoutes[].idParam` | `string` | Query parameter used to pick the DO instance. Defaults to `'id'`. |
+| `wsRoutes[].forwardPath` | `string` | Path forwarded inside the DO. Defaults to `'/websocket'`. |
+
+Remember the split:
+
+- `files.routes` is app routing
+- top-level `routes` is Cloudflare deployment routing
+- `wsRoutes` is local dev-time WebSocket proxy routing for Durable Objects
+
+#### `vars` and `secrets`
+
+| Property | Shape | Current behavior |
+|---|---|---|
+| `vars` | `Record<string, string>` | Non-secret runtime bindings compiled into Wrangler `vars` |
+| `secrets` | `Record<string, { required?: boolean }>` | Secret declarations only. `required` defaults to `true`. Values must come from Cloudflare secrets, tests, or upstream local tooling. |
+
+#### `assets`, `limits`, and `observability`
+
+| Property | Shape | Current behavior |
+|---|---|---|
+| `assets.directory` | `string` | Required asset directory path |
+| `assets.binding` | `string` | Optional asset binding name for programmatic access |
+| `limits.cpu_ms` | `number` | Optional CPU limit for unbound workers |
+| `observability.enabled` | `boolean` | Enable Worker Logs |
+| `observability.head_sampling_rate` | `number` | Log sampling rate from `0` to `1` |
+
+#### `migrations`
+
+Each migration object has this shape:
+
+| Field | Shape | Meaning |
+|---|---|---|
+| `tag` | `string` | Required migration version label |
+| `new_classes` | `string[]` | Newly introduced DO classes |
+| `renamed_classes` | `Array<{ from: string; to: string }>` | DO class renames with state preservation |
+| `deleted_classes` | `string[]` | Deleted DO classes |
+| `new_sqlite_classes` | `string[]` | DO classes migrating to SQLite storage |
+
+#### `rolldown`
+
+`rolldown` config applies to Devflare's Durable Object bundler.
+
+| Key | Shape | Current behavior |
+|---|---|---|
+| `target` | `string` | Bundle target for emitted DO bundles |
+| `minify` | `boolean` | Minify DO bundles |
+| `sourcemap` | `boolean` | Emit source maps for DO bundles |
+| `options` | `DevflareRolldownOptions` | Additional Rolldown input/output options and plugins, minus Devflare-owned fields |
+
+Current `rolldown.options` ownership rules:
+
+- Devflare owns `cwd`, `input`, `platform`, and `watch`
+- Devflare also owns output `codeSplitting`, `dir`, `file`, `format`, and `inlineDynamicImports`
+- output stays single-file ESM so the local DO bundling story remains worker-friendly
+- `rolldown.options.plugins` is the intended extension point for custom transforms and Rollup-compatible plugins
+
+#### `vite`
+
+`vite` is the Devflare-side Vite metadata namespace, not the place for raw Vite app config.
+
+| Key | Shape | Current behavior |
+|---|---|---|
+| `plugins` | `unknown[]` | Accepted by the schema and normalized from the legacy top-level `plugins` alias |
+| any other key | `unknown` | Preserved by the schema as Devflare-level Vite metadata, but raw Vite server/build/resolve/plugin wiring still belongs in local `vite.config.*` |
+
+That distinction is intentional:
+
+- put real Vite config in `vite.config.ts`
+- use `devflare/vite` helpers when Devflare needs to participate in the Vite pipeline
+- treat `config.vite` as Devflare-owned metadata, not as a drop-in replacement for Vite's own config file
+
+#### `env`
+
+`env` is `Record<string, EnvOverride>`, where each environment can currently override these keys:
+
+- `name`
+- `compatibilityDate`
+- `compatibilityFlags`
+- `files`
+- `bindings`
+- `triggers`
+- `vars`
+- `secrets`
+- `routes`
+- `assets`
+- `limits`
+- `observability`
+- `migrations`
+- `rolldown`
+- `vite`
+- `wrangler`
+- deprecated `build`
+- deprecated `plugins`
+
+Current exclusions still matter:
+
+- `accountId` is not supported inside `env`
+- `wsRoutes` is not supported inside `env`
+- nested `env` blocks are not part of the override shape
+
+Merge behavior is also part of the contract:
+
+- scalars override base values
+- nested objects merge
+- arrays append instead of replacing
+- `null` and `undefined` do not delete inherited values
+
+#### `wrangler`
+
+`wrangler` currently exposes one native child key:
+
+| Key | Shape | Current behavior |
+|---|---|---|
+| `passthrough` | `Record<string, unknown>` | Shallow-merged on top of the compiled Wrangler config. Use this for unsupported Wrangler keys or to take full ownership of `main`. |
+
+#### Deprecated aliases
+
+| Legacy key | Current canonical key | Notes |
+|---|---|---|
+| `build.target` | `rolldown.target` | Deprecated but still normalized |
+| `build.minify` | `rolldown.minify` | Deprecated but still normalized |
+| `build.sourcemap` | `rolldown.sourcemap` | Deprecated but still normalized |
+| `build.rolldownOptions` | `rolldown.options` | Deprecated but still normalized |
+| `plugins` | `vite.plugins` | Deprecated top-level alias; raw Vite plugin wiring still belongs in `vite.config.*` |
+
 ### Native config coverage vs `wrangler.passthrough`
 
 Devflare natively models the common Worker config it actively composes around. It does **not** try to mirror every Wrangler field one-by-one as a first-class Devflare schema key.
@@ -579,7 +810,7 @@ Two practical rules:
 | `entrypoints` | <code>string &#124; false</code> | `**/ep.*.{ts,js}` | WorkerEntrypoint discovery glob |
 | `workflows` | <code>string &#124; false</code> | `**/wf.*.{ts,js}` | workflow discovery glob |
 | `routes` | <code>{ dir, prefix? } &#124; false</code> | `src/routes` when that directory exists | built-in file router configuration |
-| `transport` | `string` | none | custom transport definition file |
+| `transport` | <code>string &#124; null</code> | `src/transport.{ts,js,mts,mjs}` when one of those files exists | custom transport definition file |
 
 Discovery does not behave identically in every subsystem:
 
@@ -615,25 +846,48 @@ export default defineConfig({
 })
 ```
 
-`files.transport` is opt-in. Devflare only loads it when `files.transport` is explicitly set, and the file must export a named `transport` object.
+`files.transport` is convention-first. `createTestContext()` auto-loads `src/transport.{ts,js,mts,mjs}` when present, a string value points at a different transport file, and `files.transport: null` disables transport loading explicitly. The file must export a named `transport` object.
 
 There is no public `files.tail` config key today.
 
-### `.env`, `vars`, `secrets`, and `config.env`
+### `.env`, `.dev.vars`, `vars`, `secrets`, and `config.env`
 
 Keep these layers separate:
 
 | Layer | Holds values? | Compiled into generated config? | Use it for |
 |---|---|---|---|
 | `.env` / `process.env` | yes | indirectly, only when your config reads from it | local process-time inputs |
+| `.env.dev` / `.env.<name>` | tool/runtime-dependent | indirectly at most, only if the surrounding tool has already populated `process.env` | local process-time variants, not a Devflare-native contract |
+| `.dev.vars` / `.dev.vars.<name>` | yes | no | local runtime secret/value files in upstream Cloudflare tooling when applicable |
 | `vars` | yes | yes | non-secret string bindings |
 | `secrets` | no, declaration only | no | required/optional runtime secret bindings |
 | `config.env` | yes, as config overlays | yes after merge | environment-specific config overrides |
 
-#### `.env` and process env
+#### `.env`, `.env.dev`, and process env
 
 `loadConfig()` does not do dotenv loading by itself. The Devflare CLI runs under Bun, and Bun may auto-load `.env` files into `process.env`.
 
+Important boundary:
+
+- Devflare sets `dotenv: false` in its config loader
+- Devflare does **not** define special first-class semantics for `.env.dev` or `.env.<name>`
+- if those files affect `process.env`, that comes from the surrounding host tool/runtime rather than a Devflare-native loader
+- config-time/build-time code can still read `process.env` inside `defineConfig()` or other Node-side tooling
+
+Treat `.env*` files as **config/build-time inputs**, not as Devflare's runtime secret system.
+
+#### `.dev.vars` and local runtime secrets
+
+Devflare does **not** currently implement its own first-class `.dev.vars` / `.dev.vars.<name>` loader for worker-only dev mode or `createTestContext()`.
+
+That means:
+
+- do not document `.dev.vars*` as a guaranteed Devflare-native feature across all modes
+- `secrets` declares the names of expected runtime secrets, but does not provide values
+- worker-only dev and `createTestContext()` should not be described as automatically materializing secret values from `.dev.vars*`
+
+In Vite-backed flows, some local runtime variable behavior may come from upstream Cloudflare/Vite tooling rather than from Devflare itself. Document that as inherited upstream behavior, not as a unified Devflare contract.
+
 #### `vars`
 
 Use `vars` for non-secret runtime values that can safely appear in generated config, such as public URLs, modes, IDs, and feature flags.
@@ -664,6 +918,135 @@ secrets: {
 
 means “`API_KEY` is a required runtime secret,” not “optional secret with no requirements.”
 
+In practice, secret **values** come from outside Devflare config:
+
+- Cloudflare-stored runtime secrets in deployed environments
+- explicit test injection or lower-level mocks in tests
+- upstream local-dev tooling when you intentionally rely on it
+
+Do not describe `secrets` as a place that stores values.
+
+#### Example files such as `.env.example` and `.dev.vars.example`
+
+Example files are a **team convention**, not a Devflare feature.
+
+Current truthful guidance:
+
+- use `.env.example` to document required config-time/build-time variables that your config or Node-side tooling reads from `process.env`
+- use `.dev.vars.example` to document expected local runtime secret names **if your project chooses to rely on upstream `.dev.vars` workflows**
+- keep example files committed with placeholder or fake values only
+- do not claim that Devflare auto-generates, auto-loads, or validates these example files today
+
+#### Canonical env and secrets layout
+
+If you want the lowest-confusion setup, use this split:
+
+- `.env.example` documents config-time/build-time inputs
+- `.dev.vars.example` documents local runtime secret names **only if your project intentionally relies on upstream `.dev.vars` workflows**
+- `devflare.config.ts` reads config-time values from `process.env`, puts safe runtime values in `vars`, and declares required runtime secret names in `secrets`
+- deployed secret values live in Cloudflare, not in your repo
+
+Recommended project shape:
+
+```text
+my-worker/
+├─ .env.example
+├─ .dev.vars.example        # optional; only if you intentionally use upstream .dev.vars flows
+├─ .gitignore
+├─ devflare.config.ts
+└─ src/
+	└─ fetch.ts
+```
+
+Example `.env.example`:
+
+```dotenv
+WORKER_NAME=my-worker
+API_ORIGIN=http://localhost:3000
+```
+
+Example `.dev.vars.example`:
+
+```dotenv
+API_KEY=replace-me
+SESSION_SECRET=replace-me
+```
+
+Typical git ignore pattern for user projects:
+
+```gitignore
+.env
+.env.*
+!.env.example
+.dev.vars
+.dev.vars.*
+!.dev.vars.example
+```
+
+Example `devflare.config.ts`:
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: process.env.WORKER_NAME ?? 'my-worker',
+	compatibilityDate: '2026-03-17',
+	files: {
+		fetch: 'src/fetch.ts'
+	},
+	vars: {
+		API_ORIGIN: process.env.API_ORIGIN ?? 'http://localhost:3000'
+	},
+	secrets: {
+		API_KEY: {},
+		SESSION_SECRET: {}
+	},
+	env: {
+		production: {
+			vars: {
+				API_ORIGIN: 'https://api.example.com'
+			}
+		}
+	}
+})
+```
+
+Example `src/fetch.ts`:
+
+```ts
+import type { FetchEvent } from 'devflare/runtime'
+
+export async function GET({ env }: FetchEvent<DevflareEnv>): Promise<Response> {
+	return Response.json({
+		origin: env.API_ORIGIN,
+		hasApiKey: Boolean(env.API_KEY),
+		hasSessionSecret: Boolean(env.SESSION_SECRET)
+	})
+}
+```
+
+Deployed runtime secrets should be created with Cloudflare/Wrangler tooling, not committed to config files or example files.
+
+Typical deployed secret flow:
+
+```bash
+bunx --bun wrangler secret put API_KEY
+bunx --bun wrangler secret put SESSION_SECRET
+```
+
+If you use named Cloudflare environments, set the secret in that environment explicitly:
+
+```bash
+bunx --bun wrangler secret put API_KEY --env production
+bunx --bun wrangler secret put SESSION_SECRET --env production
+```
+
+Practical rule of thumb:
+
+- if a value is needed while evaluating config, put it in the `.env*` / `process.env` bucket
+- if a value should exist as a runtime binding but must not be committed, declare it in `secrets`
+- if a project wants local runtime secret files, treat `.dev.vars*` as an upstream convention and document it explicitly per project
+
 #### `devflare types`
 
 `devflare types` generates `env.d.ts` from the resolved config plus discovered surfaces. The stable public result is typed `DevflareEnv` coverage for bindings such as `vars`, `secrets`, services, Durable Objects, and discovered entrypoints.
@@ -937,6 +1320,21 @@ Advanced members such as `.name`, `.config`, `.configPath`, and `.resolve()` are
 
 ## Development workflows
 
+### Vite vs Rolldown: the truthful mental model
+
+They are both important, but they are not two names for the same job.
+
+| Tool | Role inside Devflare | When it matters most | What it is not |
+|---|---|---|---|
+| `Vite` | the optional outer dev/build host for packages that are already Vite apps or frameworks; Devflare plugs generated Worker config, config watching, auxiliary DO workers, and bridge behavior into that pipeline | packages with a local `vite.config.*`, SvelteKit, frontend HMR | not Devflare's own Worker bundler |
+| `Rolldown` | the inner code-transforming builder Devflare uses when Devflare itself bundles Worker code | Durable Object bundles, watch/rebuild, worker-side plugin transforms such as `.svelte` imported by a DO module | not the main app's Vite build |
+
+Three practical consequences fall straight out of the implementation:
+
+- remove `vite.config.*`, and Devflare drops back to worker-only mode instead of starting Vite
+- import `.svelte` from a Durable Object, and the compilation belongs to `rolldown.options.plugins`, not to the main Vite plugin chain
+- generated `.devflare/worker-entrypoints/main.ts` is separate glue code produced by Devflare when it needs to compose fetch, queue, scheduled, email, or route-tree surfaces into one Worker entry
+
 ### Operational decision rules
 
 Use these rules in order:
@@ -948,6 +1346,278 @@ Use these rules in order:
 5. treat `.devflare/*`, `env.d.ts`, and generated Wrangler config as outputs, not authoring inputs
 6. remote mode is mainly for remote-oriented services such as AI and Vectorize, not a blanket “make everything remote” switch
 
+### Vite-backed workflows
+
+A package enters Vite-backed mode when it has a local `vite.config.*`. In that mode, Vite is the outer application pipeline: it owns the package's dev server and app build, while Devflare injects Worker-aware config, generated Wrangler output, auxiliary DO worker config, and bridge behavior into that Vite stack.
+
+Current Vite-backed flow:
+
+1. Devflare loads and validates `devflare.config.*`
+2. `devflarePlugin()` compiles that config into a generated `.devflare/wrangler.jsonc`
+3. Devflare may generate `.devflare/worker-entrypoints/main.ts` when multiple surfaces must be composed into one Worker entry
+4. if Durable Object files are discovered, Devflare builds an auxiliary DO worker config for Vite / Cloudflare interop
+5. in serve mode, Devflare watches the resolved Devflare config file and triggers a full reload when it changes
+6. if `wsRoutes` are configured, Devflare can proxy matching WebSocket upgrade paths to the Miniflare bridge
+7. on build, Devflare runs `bunx vite build` only after it has prepared the Worker config for that package
+
+Two ownership rules matter here:
+
+- setting `wrangler.passthrough.main` tells Devflare to preserve your explicit Worker `main` instead of generating a composed one
+- no local `vite.config.*` means none of this Vite-specific behavior runs; the package stays in worker-only mode
+
+#### `devflare/vite` helpers
+
+| Helper | Use it for | Timing |
+|---|---|---|
+| `devflarePlugin(options)` | generated `.devflare/wrangler.jsonc`, config watching, DO discovery, DO transforms, and WebSocket proxy wiring | include it in `vite.config.*` plugins |
+| `getCloudflareConfig(options)` | compiled programmatic config for `cloudflare({ config })` | call during Vite config creation |
+| `getDevflareConfigs(options)` | compiled config plus `auxiliaryWorkers` array for DO workers | call during Vite config creation |
+| `getPluginContext()` | read resolved plugin state such as `wranglerConfig`, `cloudflareConfig`, discovered DOs, and `projectRoot` | advanced use only, after Vite has resolved config |
+
+`devflarePlugin(options)` currently supports these options:
+
+| Option | Default | What it changes |
+|---|---|---|
+| `configPath` | auto-resolve local supported config | point Vite at a specific `devflare.config.*` file |
+| `environment` | no explicit override | resolve `config.env[name]` before compilation |
+| `doTransforms` | `true` | enable or disable Devflare's DO code transforms |
+| `watchConfig` | `true` | watch the resolved config file and full-reload on change |
+| `bridgePort` | `process.env.DEVFLARE_BRIDGE_PORT`, then `8787` when proxying | choose the Miniflare bridge port for WebSocket proxying |
+| `wsProxyPatterns` | `[]` | add extra WebSocket proxy patterns beyond configured `wsRoutes` |
+
+Timing rule of thumb:
+
+- if you need config while building the Vite config object, use `getCloudflareConfig()` or `getDevflareConfigs()`
+- if another Vite plugin needs to inspect the already-resolved Devflare state, `getPluginContext()` is the advanced hook
+
+#### Minimal Vite wiring
+
+```ts
+import { defineConfig } from 'vite'
+import { devflarePlugin } from 'devflare/vite'
+
+export default defineConfig({
+	plugins: [devflarePlugin()]
+})
+```
+
+#### Explicit `@cloudflare/vite-plugin` wiring
+
+```ts
+import { defineConfig } from 'vite'
+import { cloudflare } from '@cloudflare/vite-plugin'
+import { devflarePlugin, getDevflareConfigs } from 'devflare/vite'
+
+export default defineConfig(async () => {
+	const { cloudflareConfig, auxiliaryWorkers } = await getDevflareConfigs()
+
+	return {
+		plugins: [
+			devflarePlugin(),
+			cloudflare({
+				config: cloudflareConfig,
+				auxiliaryWorkers: auxiliaryWorkers.length > 0 ? auxiliaryWorkers : undefined
+			})
+		]
+	}
+})
+```
+
+That is the current high-signal pattern when you want Vite to stay the package's app/build host while Devflare owns Worker config compilation and Durable Object discovery.
+
+#### SvelteKit-backed Worker example
+
+```ts
+// devflare.config.ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'notes-app',
+	files: {
+		fetch: '.svelte-kit/cloudflare/_worker.js',
+		durableObjects: 'src/do/**/*.ts',
+		transport: 'src/transport.ts'
+	},
+	bindings: {
+		durableObjects: {
+			CHAT_ROOM: 'ChatRoom'
+		}
+	}
+})
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { sveltekit } from '@sveltejs/kit/vite'
+import { devflarePlugin } from 'devflare/vite'
+
+export default defineConfig({
+	plugins: [
+		devflarePlugin(),
+		sveltekit()
+	]
+})
+```
+
+```ts
+// src/hooks.server.ts
+export { handle } from 'devflare/sveltekit'
+```
+
+Use `createHandle({...})` from `devflare/sveltekit` when you need custom binding hints or want to compose Devflare with other SvelteKit handles via `sequence(...)`.
+
+### Rolldown bundling and plugin workflows
+
+`rolldown` is not just a namespace of knobs. Rolldown is the builder Devflare uses for the code Devflare actively bundles itself. Today that means the Durable Object path: Devflare discovers DO source files, applies its own transforms, lets user plugins transform imports, and emits runnable single-file ESM Worker modules that Miniflare can execute.
+
+That is why `rolldown` is important but different from Vite:
+
+- Vite may host the outer app or framework pipeline
+- Rolldown is the inner code-transform step that turns DO source into actual runnable worker code
+- if a Durable Object imports `.svelte`, that compilation belongs to the Rolldown plugin pipeline, not to the main Vite app plugin chain
+
+It is still not Vite config, not a replacement for your app's `vite.config.*`, and not the place to configure the main fetch build.
+
+Current DO bundler behavior:
+
+- Devflare discovers DO files from `files.durableObjects`
+- discovered DO entries are bundled to worker-compatible ESM
+- code splitting is disabled so Devflare can emit a worker-friendly single-file bundle
+- user `rolldown.options.plugins` are merged into the bundle pipeline
+- internal externals cover `cloudflare:*`, `node:*`, and other worker/runtime modules that should stay external
+- Devflare also injects a `debug` alias shim so worker bundles do not accidentally drag in a Node-only debug dependency
+- this same DO bundling path still matters in unified Vite dev; Vite can host the app while Rolldown rebuilds DO worker code underneath it
+
+Rolldown's plugin API is almost fully compatible with Rollup's, which is why Rollup-style plugins can often be passed through in `rolldown.options.plugins`. That said, compatibility is high, not magical: keep integration tests around nontrivial plugin stacks.
+
+#### Minimal custom transform example
+
+```ts
+import { defineConfig } from 'devflare'
+import type { Plugin as RolldownPlugin } from 'rolldown'
+
+const inlineSvelteFixturePlugin: RolldownPlugin = {
+	name: 'inline-svelte-fixture',
+	transform(_code, id) {
+		if (!id.endsWith('.svelte')) {
+			return null
+		}
+
+		return {
+			code: 'export default { render() { return { html: "<h1>Hello from Svelte</h1>" } } }',
+			map: null
+		}
+	}
+}
+
+export default defineConfig({
+	name: 'do-worker',
+	files: {
+		durableObjects: 'src/do/**/*.ts'
+	},
+	bindings: {
+		durableObjects: {
+			GREETER: 'Greeter'
+		}
+	},
+	rolldown: {
+		options: {
+			plugins: [inlineSvelteFixturePlugin]
+		}
+	}
+})
+```
+
+That mirrors the kind of `.svelte` transform path the repo's own DO bundler tests exercise.
+
+#### Svelte plugin example for Rolldown
+
+This example is intentionally about a `.svelte` import inside a Durable Object module. In that situation, Rolldown — not the main Vite app build — is the plugin pipeline doing the compilation.
+
+For this pattern you typically install `svelte`, `rollup-plugin-svelte`, and `@rollup/plugin-node-resolve` in the package that owns the Durable Object code.
+
+```ts
+import { defineConfig } from 'devflare'
+import resolve from '@rollup/plugin-node-resolve'
+import type { Plugin as RolldownPlugin } from 'rolldown'
+import svelte from 'rollup-plugin-svelte'
+
+export default defineConfig({
+	name: 'chat-worker',
+	files: {
+		durableObjects: 'src/do/**/*.ts'
+	},
+	bindings: {
+		durableObjects: {
+			CHAT_ROOM: 'ChatRoom'
+		}
+	},
+	rolldown: {
+		target: 'es2022',
+		sourcemap: true,
+		options: {
+			plugins: [
+				svelte({
+					emitCss: false,
+					compilerOptions: {
+						generate: 'ssr'
+					}
+				}) as unknown as RolldownPlugin,
+				resolve({
+					browser: true,
+					exportConditions: ['svelte'],
+					extensions: ['.svelte']
+				}) as unknown as RolldownPlugin
+			]
+		}
+	}
+})
+```
+
+```svelte
+<!-- src/do/Greeting.svelte -->
+<script lang='ts'>
+	export let name: string
+</script>
+
+<h1>Hello {name} from Svelte</h1>
+```
+
+```ts
+// src/do/chat-room.ts
+import { DurableObject } from 'cloudflare:workers'
+import Greeting from './Greeting.svelte'
+
+export class ChatRoom extends DurableObject {
+	async fetch(): Promise<Response> {
+		return new Response(Greeting.render({ name: 'Devflare' }).html, {
+			headers: {
+				'content-type': 'text/html; charset=utf-8'
+			}
+		})
+	}
+}
+```
+
+What happens in this flow:
+
+1. Devflare discovers `src/do/**/*.ts` from `files.durableObjects`
+2. the DO module imports `Greeting.svelte`
+3. Rolldown runs the configured plugin pipeline, including `rollup-plugin-svelte`
+4. the Svelte component becomes JavaScript before the DO bundle is written
+5. Devflare writes a runnable single-file Worker bundle for that DO
+
+Why this example is shaped that way:
+
+- `emitCss: false` keeps the DO bundle single-file instead of emitting a separate CSS asset pipeline
+- `generate: 'ssr'` fits the Worker-side rendering story better than a browser DOM target
+- `@rollup/plugin-node-resolve` helps `.svelte` files and `exports.svelte` packages resolve cleanly
+- some Rollup plugins need a type cast to satisfy Rolldown's TypeScript types even when the runtime hooks work fine
+- this example is specifically about worker-side component compilation inside a DO; if your Svelte code lives in the main app or SvelteKit shell, that outer build is still Vite's job
+
+If a plugin relies on Rollup-only hooks that Rolldown does not support yet, keep that plugin in your main Vite build instead of the DO bundler.
+
 ### Daily development loop
 
 Use the same CLI loop for both worker-only and Vite-backed packages. The presence of a local `vite.config.*` changes the mode automatically.
@@ -1013,7 +1683,8 @@ Current behavior:
 - it resolves service bindings and cross-worker Durable Object references
 - it can infer conventional fetch, queue, scheduled, and email handler files when present
 - it also auto-detects `src/tail.ts` when present, even though there is no public `files.tail` config key
-- `files.transport` is opt-in rather than auto-loaded by filename convention
+- it auto-detects `src/transport.{ts,js,mts,mjs}` when present unless `files.transport` is `null`
+- it does not have a first-class `.dev.vars*` loader for populating declared secret values
 
 Practical example:
 
@@ -1099,12 +1770,17 @@ Keep these caveats explicit:
 - `_`-prefixed files and directories inside the route tree are ignored
 - `vars` values are strings in the current native schema
 - `secrets` declares runtime secret bindings; it does not store secret values
+- `.env*` and `.dev.vars*` are not a unified Devflare-native loading/validation system; any effect they have comes from Bun or upstream Cloudflare tooling, depending on the mode
 - `wrangler.passthrough` is the escape hatch for unsupported Wrangler keys and is merged after native compilation
 - named service entrypoints need deployment-time validation if they are critical to your app
 - local R2 binding support is real, but there is still no stable public/browser local bucket URL contract to document as public API
 - `sendEmail` is a supported outbound binding, while inbound email is a separate worker surface
 - email and tail helpers have real, useful test paths, but they should not be described as identical to full Cloudflare ingress or tail replay
 - Vite and Rolldown are different systems and should not be blurred together
+- `rolldown` config affects Durable Object bundling, not the main Vite app build
+- `wrangler.passthrough.main` suppresses Devflare's composed main-entry generation in higher-level build and Vite-backed flows
+- `getCloudflareConfig()` and `getDevflareConfigs()` are the safe config-time Vite helpers; `getPluginContext()` is advanced post-resolution state
+- Rollup-compatible plugins often work in `rolldown.options.plugins`, but compatibility is high-not-total and plugin-specific validation still matters
 - higher-level flows may generate composed main worker entries more aggressively than older docs implied
 
 ---