StuDev.Aspire.Hosting.Cloudflare 0.1.0-preview.2

StuDev.Aspire.Hosting.Cloudflare

A .NET Aspire hosting integration for Cloudflare Workers. It orchestrates wrangler dev as an Aspire resource and models R2, D1, KV, Queues, Durable Objects and Containers as nested sub-resources in the dashboard — with health checks, vars/secrets, parallel-worktree isolation, and aspire deploy → wrangler deploy.

Preview. APIs may change.

Install

dotnet add package StuDev.Aspire.Hosting.Cloudflare --prerelease

Usage (C# AppHost)

var builder = DistributedApplication.CreateBuilder(args);

var web = builder.AddCloudflareWorker("web", "../worker");   // runs `wrangler dev`
web.AddKvNamespace("cache");        // -> env.CACHE
web.AddR2Bucket("artifacts");       // -> env.ARTIFACTS
web.AddD1Database("symbols");       // -> env.SYMBOLS
web.AddDurableObject("counter", className: "Counter");       // -> env.COUNTER
web.AddContainer("backend", className: "ApiContainer", image: "./Dockerfile"); // container-backed DO

web.WithLocalExplorer();            // dashboard link to Cloudflare's Local Explorer

// Config & service discovery into the worker's `env`:
var apiKey = builder.AddParameter("apiKey", secret: true);
web.WithVar("GREETING", "hello");   // plain var
web.WithVar("API_KEY", apiKey);     // secret -> generated env file (never on the CLI)
web.WithReference(builder.AddConnectionString("db", /* ... */)); // -> env.DB

builder.Build().Run();

The TypeScript AppHost surface (addCloudflareWorker(...), addR2Bucket(...), …) is generated automatically from the C# [AspireExport] API.

Already have bindings in wrangler.jsonc?

You don't have to re-declare them. AddCloudflareWorker reads the worker's wrangler.jsonc and surfaces any bindings it already declares (KV / R2 / D1 / Queues / Durable Objects / Containers) as read-only child resources in the dashboard — so a worker whose bindings live in its own config still shows the full picture, with no Add* calls needed:

var web = builder.AddCloudflareWorker("web", "../worker");
// nothing else — CACHE, ARTIFACTS, the container, etc. declared in wrangler.jsonc
// appear automatically as children of `web`.

This is representation only: reflected bindings are not merged into a generated config (wrangler already owns them). An explicit Add* for the same binding name supersedes the reflected one, so you can mix the two — own a couple of bindings from the AppHost while the rest come from wrangler.jsonc. Pass reflectWranglerBindings: false to opt out and get a bare worker node. Reflection covers wrangler.jsonc/wrangler.json (jsonc comments and trailing commas are fine); wrangler.toml is not parsed.

What it does

• Worker — wraps wrangler dev: proxyless endpoint (websockets/inspector work), an Aspire-allocated free port, a per-git-worktree --name (parallel worktrees don't collide), managed inspector port, and an HTTP health check.
• Bindings as sub-resources — R2 / D1 / KV / Queues / Durable Objects / Containers nest under the worker. Bindings declared in the AppHost are merged into a generated wrangler config; bindings already in your wrangler.jsonc are reflected into the dashboard as-is. Either way your wrangler.jsonc is never modified.
• Containers — container-backed Durable Objects build and run under the local container runtime; the wrangler-spawned container is surfaced live (status + logs) in the dashboard.
• Config/secrets — WithVar (literals, parameters, secrets) injected via wrangler dev --env-file; secrets never appear in command-line args.
• Deploy — aspire deploy runs wrangler deploy per worker.
• Local Explorer — WithLocalExplorer() adds a dashboard link to Cloudflare's Local Explorer (/cdn-cgi/explorer) so you can browse and edit the worker's local KV / R2 / D1 / Durable Object / Workflow data in the browser. Requires Wrangler 4.82.1+.

License

MIT