devflare 0.0.0 → 1.0.0-next.1

package/LLM.md

@@ -0,0 +1,976 @@
+# Devflare
+
+This file is for LLMs and developers **using** the `devflare` library.
+
+It explains the public mental model, the intended project structure, and the practical authoring patterns that make Devflare different from using raw Wrangler + Miniflare directly.
+
+It does **not** document the internal repository layout or example cases. Treat it as package-facing guidance.
+
+---
+
+## What Devflare is
+
+Devflare is a **developer platform for Cloudflare Workers built on top of Miniflare, Wrangler-compatible config, and framework-aware tooling**.
+
+The short version:
+
+> Miniflare gives you a local Workers runtime. Devflare turns that runtime into a coherent developer system.
+
+Devflare does this by combining:
+
+- typed config via `defineConfig()`
+- convention-driven file discovery
+- binding compilation to Wrangler-compatible config
+- local Miniflare orchestration
+- Node ↔ Worker bridging where needed
+- dedicated test helpers for each handler type
+- framework integration for Vite and SvelteKit
+- local development features that Miniflare alone does not provide cleanly, such as **browser rendering support**, multi-surface orchestration, and a consistent file-structured app model
+
+If you are building Cloudflare applications and want more structure than a single `worker.ts` plus manual plumbing, Devflare is the layer that supplies that structure.
+
+---
+
+## How Devflare extends Miniflare
+
+This is the most important concept to understand.
+
+Devflare is **not** trying to replace Miniflare. It **extends** Miniflare so developers can work with a higher-level application model.
+
+### Raw Miniflare gives you a runtime
+
+Miniflare is excellent at local execution and local emulation of many Cloudflare bindings.
+
+But by itself, it does not define:
+
+- how your project should be structured
+- how `fetch`, `queue`, `scheduled`, `email`, routes, DOs, and entrypoints should relate
+- how cross-worker references should stay typed
+- how tests should address each handler surface consistently
+- how framework output and auxiliary workers should be wired together
+- how to simulate browser rendering locally in a coherent workflow
+
+### Devflare adds the missing platform layer
+
+Devflare adds those higher-level capabilities on top of Miniflare.
+
+Concretely, it provides:
+
+1. **Convention-first file structure**
+   - `src/fetch.ts`
+   - `src/queue.ts`
+   - `src/scheduled.ts`
+   - `src/email.ts`
+   - `src/routes/**`
+   - `do.*.ts`
+   - `ep.*.ts`
+   - `wf.*.ts`
+   - `src/transport.ts`
+
+2. **Config compilation**
+   - Devflare compiles your config into Wrangler-compatible config rather than making you hand-maintain the low-level representation yourself.
+
+3. **Responsibility isolation**
+   - Instead of one giant worker file containing every concern, Devflare encourages one surface per responsibility: fetch, queue, cron, email, routes, Durable Objects, WorkerEntrypoints, workflows, and transport.
+
+4. **Unified testing surface**
+   - `cf.worker`
+   - `cf.queue`
+   - `cf.scheduled`
+   - `cf.email`
+   - `cf.tail`
+
+5. **Bridge-backed local development**
+   - Devflare handles Node-side access, env access, transport decoding, and Miniflare orchestration so tests and tooling feel like one system.
+
+6. **Capabilities beyond raw Miniflare**
+   - most notably **browser rendering support** through a local browser shim that lets browser-rendering workflows run locally in a way Miniflare does not provide directly
+
+7. **Framework integration**
+   - Vite and SvelteKit support with config generation, worker-aware transforms, auxiliary Durable Object workers, and websocket-aware local dev workflows
+
+So the design goal is not just “run a Worker locally”.
+
+The design goal is:
+
+> let developers build Cloudflare systems using coherent, isolated responsibilities while Devflare composes those responsibilities into a working local and testable whole
+
+---
+
+## The authoring model Devflare wants you to use
+
+Devflare is opinionated in a useful way.
+
+It wants you to think in **surfaces** rather than in “one file that does everything”.
+
+### HTTP surface
+
+Use `src/fetch.ts` for normal request handling.
+
+### Queue surface
+
+Use `src/queue.ts` for queue consumers.
+
+### Scheduled surface
+
+Use `src/scheduled.ts` for cron triggers.
+
+### Email surface
+
+Use `src/email.ts` for incoming email handling. Use `sendEmail` bindings in config for outgoing email.
+
+### Routing surface
+
+Use `files.routes` with a directory like `src/routes` when you want file-based HTTP routing instead of one monolithic fetch file.
+
+### Durable Object surface
+
+Use `do.*.ts` files for Durable Objects.
+
+### RPC / service-entry surface
+
+Use `ep.*.ts` files for named WorkerEntrypoints.
+
+### Workflow surface
+
+Use `wf.*.ts` files for Workflow classes.
+
+### Transport surface
+
+Use `src/transport.ts` when values crossing boundaries need custom serialization.
+
+This is one of Devflare’s biggest advantages: it turns Cloudflare development from “single worker blob” into **separated, discoverable, testable responsibilities**.
+
+---
+
+## Public package entry points
+
+Use the package subpaths intentionally.
+
+| Import | Use for |
+|---|---|
+| `devflare` | config, `ref()`, `env`, bridge/test convenience exports |
+| `devflare/runtime` | runtime-safe utilities for Worker code |
+| `devflare/test` | test context, mocks, `cf.*` helpers |
+| `devflare/vite` | Vite integration |
+| `devflare/sveltekit` | SvelteKit integration |
+| `devflare/cloudflare` | Cloudflare-specific helpers |
+| `devflare/decorators` | decorators such as `durableObject()` |
+
+---
+
+## Core ideas you should internalize
+
+### `defineConfig()` is the center of the project
+
+Always define your worker through `defineConfig()`.
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'my-worker'
+})
+```
+
+This is the source of truth Devflare uses to:
+
+- understand your bindings
+- understand your file layout
+- generate Wrangler-compatible config
+- drive dev mode
+- drive test mode
+
+### Convention beats boilerplate
+
+If your filenames follow the defaults, you do not need to spell everything out.
+
+Defaults include:
+
+- `src/fetch.ts`
+- `src/queue.ts`
+- `src/scheduled.ts`
+- `src/email.ts`
+- `src/transport.ts`
+- `**/do.*.{ts,js}`
+- `**/ep.*.{ts,js}`
+- `**/wf.*.{ts,js}`
+
+### `ref()` is how cross-worker systems stay clean
+
+If one worker depends on another worker or on another worker’s Durable Objects, use `ref()` instead of manually duplicating names.
+
+That keeps cross-worker relationships typed and centralized.
+
+### `env` is the unified access point
+
+Use:
+
+```ts
+import { env } from 'devflare'
+```
+
+Devflare makes `env` work coherently across request handling, tests, and bridge-backed local flows.
+
+---
+
+## Why file structure matters so much in Devflare
+
+In plain Worker setups, it is common to end up with a single file that mixes:
+
+- HTTP routing
+- queue handling
+- scheduled jobs
+- email handling
+- Durable Object exports
+- auxiliary RPC handlers
+- test-specific wiring
+
+Devflare pushes in the opposite direction.
+
+It gives each responsibility a natural home and then composes them together.
+
+That has several benefits:
+
+- lower mental overhead
+- easier code generation
+- easier code review
+- easier testing
+- fewer accidental runtime coupling mistakes
+- clearer ownership boundaries within a team
+
+For LLM generation specifically, this matters a lot.
+
+When generating Devflare code, prefer **separate files with clear responsibilities** over giant all-in-one worker files.
+
+---
+
+## Config example
+
+This is a good realistic starting point.
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'my-app',
+	files: {
+		routes: {
+			dir: 'src/routes',
+			prefix: '/api'
+		}
+	},
+	bindings: {
+		kv: {
+			CACHE: 'cache-kv-id'
+		},
+		d1: {
+			DB: 'db-id'
+		},
+		r2: {
+			FILES: 'files-bucket'
+		},
+		durableObjects: {
+			COUNTER: 'Counter'
+		},
+		queues: {
+			producers: {
+				TASK_QUEUE: 'task-queue'
+			},
+			consumers: [
+				{
+					queue: 'task-queue',
+					maxBatchSize: 10,
+					maxRetries: 3
+				}
+			]
+		},
+		browser: {
+			binding: 'BROWSER'
+		}
+	},
+	triggers: {
+		crons: ['0 */6 * * *']
+	},
+	vars: {
+		LOG_LEVEL: 'info'
+	}
+})
+```
+
+---
+
+## File-based routing
+
+Devflare supports a file-structured routing model through `files.routes`.
+
+That is important because it moves you away from hand-written request dispatch in one file and toward a more maintainable app structure.
+
+Example:
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'my-api',
+	files: {
+		routes: {
+			dir: 'src/routes',
+			prefix: '/api'
+		}
+	}
+})
+```
+
+Conceptually, this means:
+
+- route files map onto URL paths
+- route handlers can stay focused on their specific endpoint logic
+- your HTTP surface can scale without turning `fetch.ts` into a switch-statement graveyard
+
+If you only need a small Worker, `src/fetch.ts` is perfect.
+
+If your HTTP surface is growing, `files.routes` is usually the better model.
+
+---
+
+## Queues: produce in one place, consume in another
+
+Devflare wants queue production and queue consumption to live in obvious places.
+
+- produce messages from `fetch` or another handler via the bound queue producer
+- consume them in `src/queue.ts`
+- test them with `cf.queue`
+
+### Queue config example
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'tasks-app',
+	bindings: {
+		queues: {
+			producers: {
+				TASK_QUEUE: 'task-queue'
+			},
+			consumers: [
+				{
+					queue: 'task-queue',
+					maxBatchSize: 10,
+					maxRetries: 3
+				}
+			]
+		},
+		kv: {
+			RESULTS: 'results-kv-id'
+		}
+	}
+})
+```
+
+### Producer example from `fetch`
+
+```ts
+import { env } from 'devflare'
+
+export default async function fetch(request: Request): Promise<Response> {
+	const url = new URL(request.url)
+
+	if (url.pathname === '/tasks') {
+		const task = {
+			id: crypto.randomUUID(),
+			type: 'resize-image'
+		}
+
+		await env.TASK_QUEUE.send(task)
+		return Response.json({ queued: true, task })
+	}
+
+	return new Response('Not found', { status: 404 })
+}
+```
+
+### Consumer example in `src/queue.ts`
+
+```ts
+import type { MessageBatch } from '@cloudflare/workers-types'
+
+type Task = {
+	id: string
+	type: string
+}
+
+export default async function queue(
+	batch: MessageBatch<Task>,
+	env: DevflareEnv
+): Promise<void> {
+	for (const message of batch.messages) {
+		try {
+			await env.RESULTS.put(
+				`result:${message.body.id}`,
+				JSON.stringify({ status: 'completed', type: message.body.type })
+			)
+			message.ack()
+		} catch {
+			message.retry()
+		}
+	}
+}
+```
+
+Authoring guidance:
+
+- put queue consumers in `src/queue.ts` unless you have a strong reason not to
+- keep message bodies plain and serializable
+- use `message.ack()` on success and `message.retry()` on failure
+- bind persistence or downstream systems in config rather than hiding them in globals
+
+---
+
+## Email: receiving and sending
+
+Devflare supports two sides of email: **receiving** incoming messages and **sending** outgoing ones.
+
+### Receiving email
+
+Export an `email` function from `src/email.ts`. Devflare wires it as the worker's incoming email handler.
+
+```ts
+// src/email.ts
+import { env } from 'devflare'
+import type { ForwardableEmailMessage } from '@cloudflare/workers-types'
+
+export async function email(message: ForwardableEmailMessage): Promise<void> {
+	const id = crypto.randomUUID()
+
+	// Log the email to KV
+	await env.EMAIL_LOG.put(
+		`email:${id}`,
+		JSON.stringify({
+			from: message.from,
+			to: message.to,
+			receivedAt: new Date().toISOString()
+		})
+	)
+
+	// Forward every incoming message to admin
+	await message.forward('admin@example.com')
+}
+```
+
+The `ForwardableEmailMessage` object also supports `message.reply(replyMessage)` for auto-responses.
+
+### Sending email (the `sendEmail` binding)
+
+To send outgoing email, declare a `sendEmail` binding in config. Each key becomes a typed `env` property of type `SendEmail`.
+
+The value object accepts an optional `destinationAddress`:
+
+- **With `destinationAddress`** — every email sent through that binding is locked to that recipient.
+- **Without it (`{}`)** — you choose the recipient at send time.
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'support-mail',
+	bindings: {
+		kv: {
+			EMAIL_LOG: 'email-log-kv-id'
+		},
+		sendEmail: {
+			// Locked destination — always delivers to admin
+			ADMIN_EMAIL: { destinationAddress: 'admin@example.com' },
+
+			// Open destination — specify per message
+			EMAIL: {}
+		}
+	}
+})
+```
+
+This produces:
+
+- `env.ADMIN_EMAIL: SendEmail` — hardcoded to `admin@example.com`
+- `env.EMAIL: SendEmail` — recipient provided at send time
+
+### Testing email
+
+Use the `email` helper from `devflare/test`:
+
+```ts
+import { email } from 'devflare/test'
+
+const response = await email.send({
+	from: 'sender@example.com',
+	to: 'recipient@example.com',
+	subject: 'Test message',
+	body: 'Hello from the test suite.'
+})
+
+expect(response.ok).toBe(true)
+```
+
+Authoring guidance:
+
+- use `src/email.ts` for incoming mail handling
+- use `message.forward(...)` for routing workflows
+- use `message.reply(...)` when implementing auto-replies
+- use `sendEmail` bindings with `destinationAddress` when the recipient is always the same
+- use `sendEmail` bindings with `{}` when you need flexible per-message recipients
+- log metadata to KV or D1 if you need observability or replay/debugging context
+
+---
+
+## Browser rendering is a real example of Devflare extending Miniflare
+
+This is worth emphasizing.
+
+Devflare supports **browser rendering** locally via a browser shim layer.
+
+That matters because browser rendering is not something Miniflare gives you directly as a complete local developer workflow.
+
+With Devflare, browser rendering becomes part of the same system as the rest of your bindings and local development story:
+
+- declare the browser binding in config
+- run the app through Devflare’s orchestration
+- use the browser capability locally with the rest of your worker system
+
+This is exactly the kind of feature that demonstrates the Devflare philosophy:
+
+> take a low-level runtime foundation, then add the higher-level orchestration developers actually need
+
+---
+
+## Durable Objects and multi-worker systems
+
+Devflare is designed to keep multi-worker and DO-heavy systems manageable.
+
+### Local Durable Objects
+
+Bind them in config:
+
+```ts
+bindings: {
+	durableObjects: {
+		COUNTER: 'Counter'
+	}
+}
+```
+
+Put their classes in `do.*.ts` files.
+
+### Complete local Durable Object example
+
+If you need to generate a normal local Durable Object and call it from HTTP code, prefer this shape.
+
+```ts
+// devflare.config.ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'sessions-app',
+	bindings: {
+		durableObjects: {
+			SESSION: 'SessionStore'
+		}
+	}
+})
+```
+
+```ts
+// src/do.session.ts
+import { DurableObject } from 'cloudflare:workers'
+
+export class SessionStore extends DurableObject<DevflareEnv> {
+	private data = new Map<string, string>()
+
+	getValue(key: string): string | null {
+		return this.data.get(key) ?? null
+	}
+
+	setValue(key: string, value: string): void {
+		this.data.set(key, value)
+	}
+
+	clearAll(): void {
+		this.data.clear()
+	}
+}
+```
+
+```ts
+// src/fetch.ts
+import { env } from 'devflare'
+
+export default async function fetch(request: Request): Promise<Response> {
+	const url = new URL(request.url)
+	const sessionId = url.searchParams.get('session') ?? 'default'
+
+	const id = env.SESSION.idFromName(sessionId)
+	const session = env.SESSION.get(id)
+
+	if (url.pathname === '/set') {
+		const key = url.searchParams.get('key') ?? 'name'
+		const value = url.searchParams.get('value') ?? 'Arthur'
+		await session.setValue(key, value)
+		return Response.json({ ok: true })
+	}
+
+	if (url.pathname === '/get') {
+		const key = url.searchParams.get('key') ?? 'name'
+		const value = await session.getValue(key)
+		return Response.json({ value })
+	}
+
+	if (url.pathname === '/clear') {
+		await session.clearAll()
+		return Response.json({ ok: true })
+	}
+
+	return new Response('Not found', { status: 404 })
+}
+```
+
+Important authoring notes:
+
+- extend `DurableObject` from `cloudflare:workers`
+- bind the namespace in `bindings.durableObjects`
+- put the class in a `do.*.ts` file so discovery works naturally
+- create a stub with `env.SESSION.get(env.SESSION.idFromName(...))`
+- keep RPC-style method inputs and outputs simple and serializable
+
+### Transport layer example: Devflare encodes and decodes for you
+
+Use `src/transport.ts` when a Worker or Durable Object returns custom classes that should survive supported RPC/test boundaries as real instances.
+
+```ts
+// src/DoubleableNumber.ts
+export class DoubleableNumber {
+	value: number
+
+	constructor(n: number) {
+		this.value = n
+	}
+
+	get double() {
+		return this.value * 2
+	}
+}
+```
+
+```ts
+// src/transport.ts
+import { DoubleableNumber } from './DoubleableNumber'
+
+export const transport = {
+	DoubleableNumber: {
+		encode: (v: unknown) => v instanceof DoubleableNumber && v.value,
+		decode: (v: number) => new DoubleableNumber(v)
+	}
+}
+```
+
+```ts
+// src/do.counter.ts
+import { DoubleableNumber } from './DoubleableNumber'
+
+export class Counter {
+	private count = 0
+
+	getValue(): DoubleableNumber {
+		return new DoubleableNumber(this.count)
+	}
+
+	increment(n: number = 1): DoubleableNumber {
+		this.count += n
+		return new DoubleableNumber(this.count)
+	}
+}
+```
+
+```ts
+// tests/counter.test.ts
+import { beforeAll, afterAll, describe, expect, test } from 'bun:test'
+import { createTestContext } from 'devflare/test'
+import { env } from 'devflare'
+import { DoubleableNumber } from '../src/DoubleableNumber'
+
+beforeAll(() => createTestContext())
+afterAll(() => env.dispose())
+
+describe('counter transport', () => {
+	test('result is decoded back into a class instance', async () => {
+		const id = env.COUNTER.idFromName('main')
+		const counter = env.COUNTER.get(id)
+		const result = await counter.increment(2)
+
+		expect(result).toBeInstanceOf(DoubleableNumber)
+		expect(result.double).toBe(4)
+	})
+})
+```
+
+What Devflare is doing for the developer:
+
+1. your DO returns `new DoubleableNumber(...)`
+2. Devflare finds a matching encoder in `src/transport.ts`
+3. the value is serialized while crossing the boundary
+4. Devflare applies the decoder on the receiving side
+5. your code gets a real `DoubleableNumber` instance back
+
+This means the developer writes the codec once and then works with real domain objects rather than manual serialization code.
+
+### Cross-worker references
+
+Use `ref()` when one worker depends on another worker or another worker’s DO bindings.
+
+```ts
+import { defineConfig, ref } from 'devflare'
+
+const authWorker = ref(() => import('../auth/devflare.config'))
+
+export default defineConfig({
+	name: 'gateway',
+	bindings: {
+		services: {
+			AUTH: authWorker.worker
+		}
+	}
+})
+```
+
+This is cleaner than scattering worker names and entrypoint names by hand throughout the codebase.
+
+---
+
+## Runtime-safe helpers
+
+Import runtime-only utilities from `devflare/runtime` when the code runs inside Workers.
+
+Important helpers include:
+
+- `sequence()`
+- `resolve()`
+- `pipe()`
+- context-related utilities
+
+Use this path when you want runtime-safe middleware composition without pulling in Node-oriented orchestration code.
+
+---
+
+## Testing model
+
+Devflare testing is one of the library’s biggest strengths.
+
+### Integration-style local tests
+
+Use `createTestContext()` when you want a real local Devflare environment backed by Miniflare orchestration.
+
+```ts
+import { beforeAll, afterAll, describe, expect, test } from 'bun:test'
+import { createTestContext, cf } from 'devflare/test'
+import { env } from 'devflare'
+
+beforeAll(() => createTestContext())
+afterAll(() => env.dispose())
+
+describe('worker', () => {
+	test('GET /health', async () => {
+		const response = await cf.worker.get('/health')
+		expect(response.status).toBe(200)
+	})
+})
+```
+
+### Mock/unit-style tests
+
+Use `createMockTestContext()`, `withTestContext()`, and the mock binding helpers when you want pure logic tests.
+
+### Why this is better than ad hoc Miniflare setup
+
+Devflare gives you a single mental model for testing each handler surface:
+
+- HTTP via `cf.worker`
+- queues via `cf.queue`
+- cron via `cf.scheduled`
+- email via `cf.email`
+- tail events via `cf.tail`
+
+That consistency is part of the value. Instead of every project inventing its own test harness, Devflare gives you one coherent interface.
+
+---
+
+## Vite and SvelteKit integration
+
+Devflare includes dedicated framework-aware entry points.
+
+### `devflare/vite`
+
+Use this when you want:
+
+- config compilation during dev and build
+- worker-aware transforms
+- auxiliary Durable Object worker generation
+- websocket-aware proxying for local development
+
+### `devflare/sveltekit`
+
+Use this when your app needs:
+
+- a Devflare-aware platform object
+- integration between SvelteKit and Worker bindings
+- local dev behavior that still fits the Devflare model
+
+This is another example of Devflare going beyond raw local runtime emulation. It helps compose framework tooling, worker bindings, auxiliary workers, and local dev behavior into one predictable setup.
+
+---
+
+## Remote-only services
+
+Some Cloudflare services are not meaningfully local.
+
+Most importantly:
+
+- Workers AI
+- Vectorize
+
+Devflare treats those as explicit remote-mode concerns rather than pretending they are fully local.
+
+That is a good thing.
+
+It keeps the local story honest while still giving you an intentional path to test remote capabilities when needed.
+
+Use the `devflare remote` workflow and guard remote-only tests appropriately.
+
+---
+
+## Generated artifacts
+
+Devflare uses `.devflare/` for generated local artifacts.
+
+Treat that directory as generated output rather than hand-authored source.
+
+---
+
+## Recommended project structure
+
+Here is a strong default layout for most projects.
+
+```text
+.
+├── devflare.config.ts
+├── env.d.ts
+├── src/
+│   ├── fetch.ts
+│   ├── queue.ts
+│   ├── scheduled.ts
+│   ├── email.ts
+│   ├── transport.ts
+│   ├── routes/
+│   ├── do.counter.ts
+│   ├── ep.admin.ts
+│   └── wf.sync.ts
+└── tests/
+    └── worker.test.ts
+```
+
+You will not always need every file.
+
+But this shape captures the Devflare philosophy well:
+
+- each capability gets an isolated home
+- config stays declarative
+- tests target named surfaces
+- local orchestration is handled by Devflare instead of bespoke glue
+
+---
+
+## Guidance for LLMs generating Devflare code
+
+When generating Devflare projects or edits, follow these rules.
+
+### Prefer conventions first
+
+Only override paths when there is a real reason.
+
+### Prefer separation of responsibilities
+
+Do **not** collapse fetch, queue, scheduled, email, DOs, and entrypoints into a single file unless the task explicitly demands that shape.
+
+### Prefer `defineConfig()`
+
+Never emit untyped ad hoc config objects when a normal Devflare config is appropriate.
+
+### Prefer `ref()` for cross-worker relationships
+
+Avoid manually duplicating worker names and binding metadata.
+
+### Prefer `devflare/test` for tests
+
+Use `createTestContext()` for integration-style tests and mock helpers for unit tests.
+
+### Prefer `env` for ergonomic binding access
+
+Use `import { env } from 'devflare'` when it improves clarity.
+
+### Respect remote-only boundaries
+
+Do not fake fully local AI or Vectorize support.
+
+### Use routing when HTTP complexity grows
+
+If the app has many endpoints, prefer `files.routes` and route files over a giant `fetch.ts` dispatcher.
+
+---
+
+## Minimal example
+
+```ts
+// devflare.config.ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'hello-worker'
+})
+```
+
+```ts
+// src/fetch.ts
+export default async function fetch(): Promise<Response> {
+	return new Response('Hello from Devflare')
+}
+```
+
+```ts
+// tests/worker.test.ts
+import { beforeAll, afterAll, describe, expect, test } from 'bun:test'
+import { createTestContext, cf } from 'devflare/test'
+import { env } from 'devflare'
+
+beforeAll(() => createTestContext())
+afterAll(() => env.dispose())
+
+describe('hello-worker', () => {
+	test('GET / returns text', async () => {
+		const response = await cf.worker.get('/')
+		expect(response.status).toBe(200)
+		expect(await response.text()).toBe('Hello from Devflare')
+	})
+})
+```
+
+---
+
+## What to remember
+
+If you remember only seven things, remember these:
+
+1. `defineConfig()` is the source of truth
+2. Devflare extends Miniflare into a full developer workflow
+3. file structure is a feature, not a side detail
+4. responsibilities should live in separate surfaces and files
+5. browser rendering is a concrete example of Devflare adding capabilities above raw Miniflare
+6. `devflare/test` gives you a coherent test API across handler types
+7. use routing, refs, and framework integrations when the app grows beyond a tiny single-worker shape