dioxus-cloudflare

The missing bridge between Dioxus server functions and Cloudflare Workers.

What It Does

Write a #[server] function once. It runs on Cloudflare Workers. The client calls it like a normal async function. No manual routing, no manual serialization, no duplicated endpoints.

// shared crate — server function
use dioxus::prelude::*;
use dioxus_cloudflare::prelude::*;

#[server]
pub async fn get_user(id: String) -> Result<User, ServerFnError> {
    let db = cf::d1("DB")?;
    db.prepare("SELECT * FROM users WHERE id = ?")
        .bind(&[id.into()])?
        .first::<User>(None)
        .await
        .cf()?
        .ok_or_else(|| ServerFnError::new("Not found"))
}

// client component — just call it
let user = get_user("abc".into()).await;

Architecture

Client WASM                    Cloudflare Worker
┌──────────┐    fetch()    ┌─────────────────────┐
│ #[server] │ ───────────▶ │ handle(req, env)     │
│ generates │              │   ↓ set_context()    │
│ POST to   │              │   ↓ worker→http req  │
│ /api/...  │              │   ↓ Axum dispatch    │
│           │ ◀── JSON ──  │   ↓ http→worker resp │
└──────────┘               │   ↓ clear_context()  │
                           └─────────────────────┘

Request Flow

1. Client calls get_user(id) — Dioxus serializes args, sends POST to /api/get_user
2. Worker #[event(fetch)] receives the request
3. dioxus_cloudflare::handle(req, env) is called:
   • Stores Env in thread-local (cf::env() becomes available)
   • Stores raw Request in thread-local (cf::req() becomes available)
   • Converts worker::Request → http::Request
   • Dispatches through the Dioxus Axum router (axum_core feature)
   • Converts http::Response → worker::Response
   • Clears thread-local context
4. Worker returns the response

Why Thread-Local Works

Cloudflare Workers run one request per isolate at a time (single-threaded WASM). There is no concurrent access to thread-locals within a single Worker invocation.

The Crate Provides

Prerequisites

This crate requires a patched version of dioxus-server that adds wasm32 target support. Add the following to your workspace Cargo.toml:

[patch.crates-io]

dioxus-server = { git = "https://github.com/JaffeSystems/dioxus-server-cf.git" }

This is necessary because upstream dioxus-server 0.7.3 does not compile for wasm32-unknown-unknown. The patch applies minimal cfg-gating to make it compatible with Cloudflare Workers.

Usage

Worker Entry Point

use worker::*;
use dioxus_cloudflare::prelude::*;

// Import server functions so they register with inventory
use shared::server_fns::*;

extern "C" { fn __wasm_call_ctors(); }

#[event(fetch)]
async fn fetch(req: Request, env: Env, _ctx: Context) -> Result<Response> {
    // Required: initialize inventory for #[server] function registration
    // SAFETY: Called once per cold start. inventory crate needs this in WASM.
    unsafe { __wasm_call_ctors(); }

    dioxus_cloudflare::handle(req, env).await
}

Server Function (Shared Crate)

use dioxus::prelude::*;
use dioxus_cloudflare::prelude::*;

#[server]
pub async fn create_order(items: Vec<Item>) -> Result<Order, ServerFnError> {
    let db = cf::d1("DB")?;

    db.prepare("INSERT INTO orders (items, total) VALUES (?, ?)")
        .bind(&[serde_json::to_string(&items)?.into(), total.into()])?
        .run()
        .await
        .cf()?;

    Ok(Order { items, total, status: "confirmed".into() })
}

Client Component

use dioxus::prelude::*;
use shared::server_fns::create_order;

#[component]
fn OrderButton(items: Vec<Item>) -> Element {
    let order = use_resource(move || {
        let items = items.clone();
        async move { create_order(items).await }
    });

    match &*order.read() {
        Some(Ok(o)) => rsx! { p { "Order confirmed: {o.status}" } },
        Some(Err(e)) => rsx! { p { "Error: {e}" } },
        None => rsx! { p { "Placing order..." } },
    }
}

Crate Structure

src/
├── lib.rs          # Public API: cf module, handle(), re-exports
├── bindings.rs     # Typed binding shorthands: d1(), kv(), r2(), durable_object(), queue()
├── context.rs      # Thread-local Env + Request storage
├── handler.rs      # handle() — Worker↔Axum request/response bridge
├── cookie.rs       # Cookie read/write helpers + CookieBuilder
├── error.rs        # CfError newtype + CfResultExt trait
└── prelude.rs      # Convenience re-exports

Implementation Status

Working end-to-end

• Thread-local context (cf::env(), cf::req())
• Typed binding shorthands (cf::d1(), cf::kv(), cf::r2(), cf::durable_object(), cf::queue())
• Durable Objects — cf::durable_object() shorthand for namespace access
• Queues — cf::queue() shorthand for producer access (requires queue feature)
• Request headers — read via cf::req() inside server functions
• Cookie reading (cf::cookie(), cf::cookies())
• Cookie writing (cf::set_cookie(), cf::clear_cookie()) — queue-based, applied to response automatically
• Configurable cookie builder (cf::set_cookie_with()) — custom SameSite, Domain, Path, Max-Age, etc.
• Error bridge (CfError, .cf()) — covers both worker::Error and KvError
• Request/response conversion (worker::Request ↔ http::Request)
• dispatch() — Axum router with ServerFunction::collect() + .oneshot()
• __wasm_call_ctors + inventory initialization
• D1 — read/write queries via cf::d1("DB")
• Workers KV — put/get/delete via cf::kv("KV")
• R2 — put/get/delete via cf::r2("BUCKET")
• Static assets via wrangler [assets] + run_worker_first = ["/api/*"]

Not yet implemented

• Streaming response support (SSE)
• SSR rendering inside Workers

SSR / Streaming Feasibility

SSR (Hard)

dioxus-server's SSR pipeline uses LocalPoolHandle (a tokio thread pool) for rendering. Cloudflare Workers run single-threaded WASM with no native thread support. The dioxus-ssr crate itself compiles to wasm, but the integration layer in dioxus-server that drives it does not. Adapting this requires a single-threaded executor replacement — a significant refactor.

Streaming (Medium)

Cloudflare Workers support ReadableStream for streaming responses. The current handler.rs collects the entire response body into Vec<u8> before sending. Streaming would require piping axum::body::Body frames into a web_sys::ReadableStream. Dioxus has transport-agnostic streaming architecture in dioxus-server, making this more tractable than full SSR.

Recommendation: Streaming server function responses first (simpler, more immediate value), full page SSR later.

Roadmap

Near-term

• Streaming responses — pipe axum::body::Body → ReadableStream for SSE and large payloads
• Middleware hooks — pre/post-dispatch hooks for auth checks, CORS, rate limiting, logging
• Template project / cargo generate — scaffolding for new dioxus-cloudflare projects with wrangler config, shared/web/worker crates, and build scripts
• Remove dioxus-server patch requirement — upstream the wasm32 cfg-gating to Dioxus core so users don't need [patch.crates-io]

Ideas / Exploration

• SSR inside Workers — requires single-threaded executor adaptation for dioxus-server's render pipeline
• Session middleware — built-in session management backed by KV or D1 with cookie-based session IDs
• WebSocket support — Durable Object + WebSocket upgrade for real-time Dioxus apps
• Service bindings — call other Workers from server functions via cf::env().service()
• AI bindings — cf::env().ai() for Workers AI inference from server functions
• Secrets — cf::env().secret() for accessing encrypted environment variables
• Wrangler plugin — automate the build pipeline (cargo build → wasm-bindgen → shim generation) without manual wrangler.toml [build] commands

Optional Features

Dependencies

dioxus = { version = "=0.7.3", features = ["fullstack"] }

worker = { version = "0.4", features = ["http"] }

axum = { version = "0.8", default-features = false }

http = "1"