devflare 0.0.0 → 1.0.0-next.0

package/README.md

@@ -1 +1,737 @@
-Something great is being built here✨
+# Devflare
+
+**Build Cloudflare Workers like an application, not a pile of glue.**
+
+Devflare is a developer-first toolkit for Cloudflare Workers that sits on top of Miniflare and Wrangler-compatible config.
+
+It gives you:
+
+- a clean file structure
+- typed config with `defineConfig()`
+- easier local development
+- great testing ergonomics
+- first-class Durable Object and multi-worker workflows
+- browser rendering support in local development
+- Vite and SvelteKit integration when your app grows up
+
+Miniflare gives you a local runtime.
+
+Devflare turns that runtime into a **coherent development system**.
+
+---
+
+## Why Devflare?
+
+Cloudflare development gets messy fast.
+
+You start with one Worker, then suddenly you have:
+
+- HTTP routes
+- queues
+- scheduled jobs
+- email handlers
+- Durable Objects
+- service bindings
+- framework output
+- test setup that no longer resembles runtime
+
+Devflare keeps those responsibilities isolated and composable.
+
+Instead of one giant worker file, you get a structure like this:
+
+```text
+.
+├── devflare.config.ts
+├── env.d.ts
+├── src/
+│   ├── fetch.ts
+│   ├── queue.ts
+│   ├── scheduled.ts
+│   ├── email.ts
+│   ├── routes/
+│   ├── do.counter.ts
+│   ├── ep.admin.ts
+│   └── transport.ts
+└── tests/
+    └── worker.test.ts
+```
+
+That structure is one of Devflare’s biggest strengths: **separate responsibilities, fewer surprises**.
+
+---
+
+## What makes it different from plain Miniflare?
+
+Devflare does not replace Miniflare.
+
+It **extends** it.
+
+Miniflare gives you local execution.
+Devflare adds the developer workflow around it:
+
+- convention-first file discovery
+- config compilation to Wrangler-compatible output
+- unified test helpers for `fetch`, `queue`, `scheduled`, `email`, and `tail`
+- typed cross-worker references with `ref()`
+- local orchestration for multi-surface Worker apps
+- browser rendering support in local development
+- framework-aware integration for Vite and SvelteKit
+
+In short:
+
+> Devflare helps you build Cloudflare systems with clear boundaries and smooth local development.
+
+---
+
+## Install
+
+For a typical project, install Devflare and Wrangler as dev dependencies:
+
+```bash
+bun add -d devflare wrangler
+```
+
+If you are using Vite integration, also install the Vite plugin dependencies:
+
+```bash
+bun add -d vite @cloudflare/vite-plugin
+```
+
+---
+
+## Quick start
+
+### 1. Create a config
+
+```ts
+// devflare.config.ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'hello-worker'
+})
+```
+
+### 2. Add a fetch handler
+
+```ts
+// src/fetch.ts
+export default async function fetch(): Promise<Response> {
+	return new Response('Hello from Devflare')
+}
+```
+
+### 3. Generate types
+
+```bash
+bunx --bun devflare types
+```
+
+This creates `env.d.ts` so your bindings and entrypoints stay typed.
+
+### 4. Start development
+
+```bash
+bunx --bun devflare dev
+```
+
+### 5. Add a test
+
+```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')
+	})
+})
+```
+
+---
+
+## The Devflare way to structure an app
+
+Devflare works best when each concern lives in its own file.
+
+### Common files
+
+| File | Purpose |
+|---|---|
+| `src/fetch.ts` | HTTP requests |
+| `src/queue.ts` | queue consumers |
+| `src/scheduled.ts` | cron handlers |
+| `src/email.ts` | email handlers |
+| `src/routes/**` | file-based routing |
+| `do.*.ts` | Durable Objects |
+| `ep.*.ts` | named WorkerEntrypoints |
+| `wf.*.ts` | workflows |
+| `src/transport.ts` | custom serialization across boundaries |
+
+This is more than style.
+
+It is how Devflare helps you keep local development, testing, and runtime behavior aligned.
+
+---
+
+## Example config
+
+```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'
+		},
+		durableObjects: {
+			COUNTER: 'Counter'
+		},
+		queues: {
+			producers: {
+				TASK_QUEUE: 'task-queue'
+			}
+		},
+		browser: {
+			binding: 'BROWSER'
+		}
+	},
+	triggers: {
+		crons: ['0 */6 * * *']
+	}
+})
+```
+
+---
+
+## Routing without the giant switch statement
+
+As your HTTP surface grows, you do not need to keep stuffing logic into `fetch.ts`.
+
+Use file-based routing instead:
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'my-api',
+	files: {
+		routes: {
+			dir: 'src/routes',
+			prefix: '/api'
+		}
+	}
+})
+```
+
+This lets your app grow naturally while keeping each endpoint focused and easy to maintain.
+
+---
+
+## Queues without extra glue
+
+Devflare gives queues a natural place in your app:
+
+- produce messages from `fetch` or other handlers
+- consume them in `src/queue.ts`
+- test them with `cf.queue`
+
+```ts
+// devflare.config.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'
+		}
+	}
+})
+```
+
+```ts
+// src/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 })
+}
+```
+
+```ts
+// src/queue.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()
+		}
+	}
+}
+```
+
+---
+
+## Email
+
+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 automatically.
+
+```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 for later inspection
+	await env.EMAIL_LOG.put(
+		`email:${id}`,
+		JSON.stringify({
+			from: message.from,
+			to: message.to,
+			receivedAt: new Date().toISOString()
+		})
+	)
+
+	// Forward to an admin address
+	await message.forward(env.FORWARD_ADDRESS)
+}
+```
+
+You can also auto-reply with `message.reply(replyMessage)` — useful for sending confirmation receipts.
+
+### Sending email
+
+To send outgoing email, declare a `sendEmail` binding. Each key becomes an `env` property of type `SendEmail`.
+
+The value is a config object that accepts an optional `destinationAddress`. When set, every email sent through that binding goes to that address. When omitted (`{}`), you specify the recipient at send time.
+
+```ts
+// devflare.config.ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'support-mail',
+	bindings: {
+		kv: {
+			EMAIL_LOG: 'email-log-kv-id'
+		},
+		sendEmail: {
+			// Locked to a specific recipient — every send goes to admin
+			ADMIN_EMAIL: { destinationAddress: 'admin@example.com' },
+
+			// Open — you choose the recipient per message
+			EMAIL: {}
+		}
+	}
+})
+```
+
+This generates two typed bindings on `env`:
+
+- `env.ADMIN_EMAIL` — always delivers to `admin@example.com`
+- `env.EMAIL` — you provide the destination when composing the message
+
+### Testing email
+
+Import the `email` helper from `devflare/test` to send test messages to your running dev server:
+
+```ts
+import { email } from 'devflare/test'
+
+const response = await email.send({
+	from: 'sender@example.com',
+	to: 'recipient@example.com',
+	subject: 'Hello from devflare',
+	body: 'This is a test email.'
+})
+
+expect(response.ok).toBe(true)
+```
+
+---
+
+## Durable Objects and multi-worker setups
+
+Devflare makes advanced Worker architecture feel much less dramatic.
+
+### Local Durable Objects
+
+```ts
+bindings: {
+	durableObjects: {
+		COUNTER: 'Counter'
+	}
+}
+```
+
+Place the class in a `do.*.ts` file and Devflare handles the discovery flow.
+
+### Write a Durable Object and call it from `fetch`
+
+This is the most common pattern:
+
+```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 })
+}
+```
+
+The flow is simple:
+
+1. bind the Durable Object in `devflare.config.ts`
+2. implement the class in a `do.*.ts` file
+3. get a stub with `env.SESSION.get(env.SESSION.idFromName(...))`
+4. call your methods from `fetch`
+
+### Cross-worker references
+
+Use `ref()` when one worker depends on another worker or its entrypoints/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
+		}
+	}
+})
+```
+
+Typed relationships, less duplication, fewer paper cuts.
+
+---
+
+## Transport for custom types, without manual serialization
+
+Sometimes your Worker or Durable Object wants to return a real class instance, not just plain JSON.
+
+That is what `src/transport.ts` is for.
+
+You define how to encode and decode a custom type **once**, and Devflare applies it for you across supported boundaries.
+
+```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
+
+	increment(n: number = 1): DoubleableNumber {
+		this.count += n
+		return new DoubleableNumber(this.count)
+	}
+}
+```
+
+```ts
+// tests/counter.test.ts
+import { beforeAll, afterAll, expect, test } from 'bun:test'
+import { createTestContext } from 'devflare/test'
+import { env } from 'devflare'
+import { DoubleableNumber } from '../src/DoubleableNumber'
+
+beforeAll(() => createTestContext())
+afterAll(() => env.dispose())
+
+test('transport restores my custom type', 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)
+})
+```
+
+The important bit: **you do not manually encode before returning or manually decode after receiving**.
+
+Devflare handles the transport step so the developer works with the real type again.
+
+---
+
+## Testing that feels like the real app
+
+Devflare ships a clean testing API through `devflare/test`.
+
+### Integration-style tests
+
+Use `createTestContext()` for real local behavior backed by Devflare’s Miniflare orchestration.
+
+### Mock-style tests
+
+Use:
+
+- `createMockTestContext()`
+- `withTestContext()`
+- `createMockKV()`
+- `createMockD1()`
+- `createMockR2()`
+- `createMockQueue()`
+
+### Unified handler helpers
+
+You can test each surface directly:
+
+- `cf.worker`
+- `cf.queue`
+- `cf.scheduled`
+- `cf.email`
+- `cf.tail`
+
+That consistency is a huge quality-of-life improvement.
+
+---
+
+## Browser rendering, locally
+
+Browser rendering is a perfect example of Devflare adding capability above raw Miniflare.
+
+With Devflare, browser rendering becomes part of the same local development story as the rest of your Worker bindings.
+
+That means you can build richer Worker applications without stitching together a separate custom local browser setup by hand.
+
+---
+
+## Framework support
+
+### `devflare/vite`
+
+Use this when you want:
+
+- config compilation during dev and build
+- worker-aware transforms
+- auxiliary Durable Object worker generation
+- websocket-aware local development
+
+### `devflare/sveltekit`
+
+Use this when your project needs:
+
+- a Devflare-aware platform layer
+- smooth SvelteKit + Worker binding integration
+- local development that still behaves like a coherent Worker system
+
+---
+
+## CLI
+
+Devflare includes a CLI for the full development loop.
+
+```text
+devflare init
+devflare dev
+devflare build
+devflare deploy
+devflare types
+devflare doctor
+devflare remote
+```
+
+Most projects will mainly use:
+
+```bash
+bunx --bun devflare dev
+bunx --bun devflare types
+bunx --bun devflare build
+```
+
+---
+
+## A good starter layout
+
+```text
+.
+├── devflare.config.ts
+├── env.d.ts
+├── src/
+│   ├── fetch.ts
+│   ├── routes/
+│   ├── queue.ts
+│   ├── scheduled.ts
+│   ├── email.ts
+│   ├── do.counter.ts
+│   ├── ep.admin.ts
+│   └── transport.ts
+└── tests/
+    └── worker.test.ts
+```
+
+Not every project needs every file.
+
+But if you follow this shape, Devflare will feel very natural.
+
+---
+
+## When to use Devflare
+
+Devflare is especially nice when you want:
+
+- Cloudflare Workers with clean project structure
+- Durable Object-heavy apps
+- multi-worker systems with service bindings
+- local-first development with realistic tests
+- browser rendering in your local workflow
+- Vite or SvelteKit apps that still want a clean Worker model
+
+---
+
+## In one sentence
+
+**Devflare helps you build Cloudflare Workers with clearer structure, better local tooling, and a development experience that scales with your app.**