devflare 1.0.0-next.10 → 1.0.0-next.12

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 runs it when the current package has a local `vite.config.*` or a non-empty `config.vite`, and Devflare merges that config into the actual Vite config it executes.
+- **Rolldown** is the inner builder Devflare uses when Devflare itself needs to transform Worker source into runnable Worker modules. Today that covers worker-only main-worker bundles and Durable Object bundles.
+
 ### Authoring model
 
 A **surface** is a distinct handler or entry file that Devflare treats as its own concern. The common surfaces are:
@@ -524,10 +530,236 @@ Secondary keys:
 | `assets` | static asset config |
 | `limits` | worker limits |
 | `wsRoutes` | local WebSocket proxy rules for dev |
-| `vite` | Devflare Vite metadata |
-| `rolldown` | worker-only bundler options |
+| `vite` | inline Vite config for Devflare-run Vite flows |
+| `rolldown` | Devflare-owned Worker 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 across worker-only main-worker bundles and Durable Object bundles. This is not a replacement for the main Vite app build. |
+| `vite` | object | no | Inline Vite config merged into the actual Vite config Devflare runs. A local `vite.config.*` remains optional and is merged first when present. |
+| `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 own Worker bundling outputs.
+
+| Key | Shape | Current behavior |
+|---|---|---|
+| `target` | `string` | Bundle target for emitted Devflare-owned Worker bundles |
+| `minify` | `boolean` | Minify Devflare-owned Worker bundles |
+| `sourcemap` | `boolean` | Emit source maps for Devflare-owned Worker 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 Devflare's worker-owned bundles remain worker-friendly
+- `rolldown.options.plugins` is the intended extension point for custom transforms and Rollup-compatible plugins
+
+#### `vite`
+
+`vite` is Devflare's inline Vite config namespace. When Devflare runs Vite, this object is merged into the actual Vite config that Vite receives.
+
+| Key | Shape | Current behavior |
+|---|---|---|
+| `plugins` | `unknown[]` | Accepted by the schema and normalized from the legacy top-level `plugins` alias, then merged into the actual Vite plugin chain when Devflare runs Vite |
+| any other key | `unknown` | Passed through as actual Vite config when Devflare runs Vite |
+
+That distinction is intentional:
+
+- use `config.vite` when you want Devflare config to be your Vite config source of truth
+- keep `vite.config.ts` when you prefer a standalone Vite config file or need advanced programmatic control
+- if both exist, Devflare merges `vite.config.*` first, then `config.vite`, and injects `devflarePlugin()` into the resulting config
+- use `devflare/vite` helpers when Devflare needs to participate in the Vite pipeline programmatically
+
+#### `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 +811,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 +847,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 +919,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,20 +1321,299 @@ 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.*`, packages that only define inline `config.vite`, SvelteKit, frontend HMR | not Devflare's own Worker bundler |
+| `Rolldown` | the inner code-transforming builder Devflare uses when Devflare itself bundles Worker code | worker-only main worker bundles, Durable Object bundles, watch/rebuild, worker-side plugin transforms such as `.svelte` imported by a worker or DO module | not the main app's Vite build |
+
+Three practical consequences fall straight out of the implementation:
+
+- remove both `vite.config.*` and inline `config.vite`, and Devflare drops back to worker-only mode instead of starting Vite
+- import `.svelte` from a worker-only surface or 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:
 
-1. a local `vite.config.*` in the current package decides whether `dev`, `build`, and `deploy` run in Vite-backed mode or worker-only mode
+1. a local `vite.config.*` or a non-empty `config.vite` in the current package decides whether `dev`, `build`, and `deploy` run in Vite-backed mode or worker-only mode
 2. `devflare/vite` is an explicit helper layer, not a separate CLI mode
-3. worker-only mode is a supported first-class path; no local `vite.config.*` means Devflare does not start Vite
-4. raw Vite config belongs in `vite.config.*`; `config.vite` is Devflare metadata, not full Vite config
+3. worker-only mode is a supported first-class path; no local `vite.config.*` and no inline `config.vite` means Devflare does not start Vite
+4. `config.vite` is real Vite config when Devflare runs Vite; a local `vite.config.*` remains optional and is merged first when present
 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.*` or a non-empty `config.vite`. 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. if a local `vite.config.*` exists, Devflare loads it and merges `config.vite` on top; otherwise Devflare synthesizes `.devflare/vite.config.mjs` from `config.vite`
+3. `devflarePlugin()` compiles that config into a generated `.devflare/wrangler.jsonc`
+4. Devflare may generate `.devflare/worker-entrypoints/main.ts` when multiple surfaces must be composed into one Worker entry
+5. if Durable Object files are discovered, Devflare builds an auxiliary DO worker config for Vite / Cloudflare interop
+6. in serve mode, Devflare watches the resolved Devflare config file and triggers a full reload when it changes
+7. if `wsRoutes` are configured, Devflare can proxy matching WebSocket upgrade paths to the Miniflare bridge
+8. on build, Devflare runs `bunx vite build --config .devflare/vite.config.mjs` when it needs a generated config wrapper
+
+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.*` and no inline `config.vite` 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 |
+| `resolveViteUserConfig(configEnv, options)` | merge local `vite.config.*`, inline `config.vite`, and `devflarePlugin()` into the actual Vite config object | advanced / generated-config use |
+| `writeGeneratedViteConfig(options)` | write `.devflare/vite.config.mjs` for CLI-driven Vite runs | advanced / generated-config use |
+| `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 you want Devflare to treat `config.vite` as the actual Vite config source of truth, rely on the CLI-generated config path or `resolveViteUserConfig()`
+- 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 two Devflare-owned output paths: the worker-only composed main worker bundle and the Durable Object bundle path. Devflare composes worker surfaces when needed, applies its own transforms, lets user plugins transform imports, and emits runnable single-file ESM Worker modules that Miniflare and Wrangler 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 Devflare-owned Worker source into actual runnable worker code
+- if a worker-only surface or 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 Vite app build.
+
+Current worker bundler behavior:
+
+- in worker-only `dev`, `build`, and `deploy`, Devflare composes the main worker entry to `.devflare/worker-entrypoints/main.ts` and then bundles it to `.devflare/worker-entrypoints/main.js`
+- 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: 'worker-app',
+	files: {
+		fetch: 'src/fetch.ts'
+	},
+	rolldown: {
+		options: {
+			plugins: [inlineSvelteFixturePlugin]
+		}
+	}
+})
+```
+
+That mirrors the kind of `.svelte` transform path the repo now exercises for the composed main worker bundle.
+
+#### Svelte plugin example for Rolldown
+
+This example is intentionally about a `.svelte` import inside a worker-only fetch surface. 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 worker 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: {
+		fetch: 'src/fetch.ts'
+	},
+	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/Greeting.svelte -->
+<script lang='ts'>
+	export let name: string
+</script>
+
+<h1>Hello {name} from Svelte</h1>
+```
+
+```ts
+// src/fetch.ts
+import Greeting from './Greeting.svelte'
+
+export async function 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 or composes the worker-only main entry from `files.fetch` and related surfaces
+2. the worker module imports `Greeting.svelte`
+3. Rolldown runs the configured plugin pipeline, including `rollup-plugin-svelte`
+4. the Svelte component becomes JavaScript before the Worker bundle is written
+5. Devflare writes a runnable single-file Worker bundle for that worker entry
+
+Why this example is shaped that way:
+
+- `emitCss: false` keeps the Worker 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 worker-only surface; the same plugin path also applies to DO bundles, while Svelte code in the main app or SvelteKit shell 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.
+Use the same CLI loop for both worker-only and Vite-backed packages. The presence of a local `vite.config.*` or inline `config.vite` changes the mode automatically.
 
 ```bash
 bunx --bun devflare dev
@@ -967,7 +1630,7 @@ Use `--env <name>` on build and deploy when you want Devflare to resolve a named
 | Command | What it does | Important note |
 |---|---|---|
 | `devflare init` | scaffold a project | current templates generate `src/fetch.ts` and explicit `files.fetch` |
-| `devflare dev` | start local development | worker-only by default, Vite-backed only when the current package has a local `vite.config.*` |
+| `devflare dev` | start local development | worker-only by default, Vite-backed when the current package has a local `vite.config.*` or inline `config.vite` |
 | `devflare build` | build from resolved config | skips Vite for worker-only packages |
 | `devflare deploy` | build and deploy | supports `--env` and `--dry-run` |
 | `devflare types` | generate `env.d.ts` | supports `--output` |
@@ -1013,7 +1676,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 +1763,18 @@ 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
+- `config.vite` is real Vite config only when Devflare is actually running Vite; it does not replace the worker-only Rolldown bundle path
+- `rolldown` config affects Devflare-owned worker bundling outputs (worker-only main bundles and DO bundles), 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
 
 ---