Cloudflare Workers setup and bindings

1234// wrangler.jsonc
{
  "main": "./src/main.tsx",
}

123456789101112131415161718// vite.config.ts
import { cloudflare } from '@cloudflare/vite-plugin'
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'
import spiceflow from 'spiceflow/vite'

export default defineConfig({
  plugins: [
    react(),
    spiceflow({ entry: './src/main.tsx' }),
    cloudflare({
      viteEnvironment: {
        name: 'rsc',
        childEnvironments: ['ssr'],
      },
    }),
  ],
})

1234567891011121314// src/main.tsx
import { Spiceflow } from 'spiceflow'

export const app = new Spiceflow().page('/', async () => {
  return <div>Hello from Cloudflare RSC</div>
})

export type App = typeof app

export default {
  fetch(request: Request) {
    return app.handle(request)
  },
}

123456{
  "scripts": {
    "dev": "FORCE_COLOR=1 vite dev",
    "build": "FORCE_COLOR=1 vite build"
  }
}

12345# Build for preview environment
CLOUDFLARE_ENV=preview vite build && wrangler deploy --env preview

# Build for production (default, no env var needed)
vite build && wrangler deploy

123456789101112131415161718192021222324252627import { Spiceflow } from 'spiceflow'
import { env } from 'cloudflare:workers'

export const app = new Spiceflow()
  .route({
    method: 'GET',
    path: '/kv/:key',
    async handler({ params }) {
      const value = await env.KV.get(params.key)
      return { key: params.key, value }
    },
  })
  .route({
    method: 'POST',
    path: '/queue',
    async handler({ request }) {
      const body = await request.json()
      await env.QUEUE.send(body)
      return { success: true, message: 'Added to queue' }
    },
  })

export default {
  fetch(request: Request) {
    return app.handle(request)
  },
}

12345678// wrangler.jsonc
{
  "observability": {
    "traces": {
      "enabled": true
    }
  }
}

123456GET /dashboard [server]
├── middleware - auth
├── loader - /dashboard        ← spiceflow span
├── page - /dashboard          ← spiceflow span
├── env.MY_KV.get("key")      ← automatic CF span
└── rsc.serialize              ← spiceflow span

123456789// wrangler.jsonc
{
  "observability": {
    "enabled": true,
    "traces": {
      "enabled": true
    }
  }
}

1234wrangler tail                    # all logs
wrangler tail --status error     # errors only
wrangler tail --search "TypeError"  # filter by text
wrangler tail --format json      # JSON output for piping to jq

1234567891011121314151617181920import { Spiceflow } from 'spiceflow'

export const app = new Spiceflow().route({
  method: 'POST',
  path: '/process',
  async handler({ request, waitUntil }) {
    const data = await request.json()

    // Schedule background task
    waitUntil(
      fetch('https://analytics.example.com/track', {
        method: 'POST',
        body: JSON.stringify({ event: 'data_processed', data }),
      }),
    )

    // Return response immediately
    return { success: true, id: Math.random().toString(36) }
  },
})

12345678910111213141516171819202122232425262728293031import { Spiceflow } from 'spiceflow'

export const app = new Spiceflow().route({
  method: 'POST',
  path: '/webhook',
  async handler({ request, waitUntil }) {
    const payload = await request.json()

    // Process webhook data in background
    waitUntil(
      processWebhookData(payload)
        .then(() => console.log('Webhook processed'))
        .catch((err) => console.error('Webhook processing failed:', err)),
    )

    // Respond immediately to webhook sender
    return new Response('OK', { status: 200 })
  },
})

async function processWebhookData(payload: any) {
  // Simulate time-consuming processing
  await new Promise((resolve) => setTimeout(resolve, 1000))
  // Save to database, send notifications, etc.
}

export default {
  fetch(request: Request) {
    return app.handle(request)
  },
}

12345678910111213141516171819202122import { Spiceflow } from 'spiceflow'

export const app = new Spiceflow({
  waitUntil: (promise) => {
    // Custom implementation for non-Cloudflare environments
    promise.catch((err) => console.error('Background task failed:', err))
  },
}).route({
  method: 'GET',
  path: '/analytics',
  async handler({ waitUntil }) {
    // Schedule analytics tracking
    waitUntil(trackPageView('/analytics'))

    return { message: 'Analytics page loaded' }
  },
})

async function trackPageView(path: string) {
  // Track page view in analytics system
  console.log(`Page view tracked: ${path}`)
}

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657import { Spiceflow, getDeploymentId } from 'spiceflow'
import { env } from 'cloudflare:workers'

export const app = new Spiceflow()
  .use(async ({ request, waitUntil }, next) => {
    if (request.method !== 'GET') {
      return next()
    }

    const { pathname, search } = request.parsedUrl
    const deploymentId = await getDeploymentId()
    const cacheKey = `${deploymentId}:${pathname}${search}` // IMPORTANT. cache key must always include search to distinguish html and rsc responses

    const cached = await env.PAGE_CACHE.get(cacheKey)
    if (cached) {
      return new Response(cached, {
        headers: {
          'content-type': 'text/html; charset=utf-8',
          'x-cache': 'HIT',
        },
      })
    }

    const response = await next()
    if (!response || response.status !== 200) {
      return response
    }

    const html = await response.text()
    // Write to KV in the background so the response is not delayed
    waitUntil(
      env.PAGE_CACHE.put(cacheKey, html, {
        expirationTtl: 60 * 60 * 24 * 7, // 7 days
      }),
    )

    return new Response(html, {
      status: 200,
      headers: {
        'content-type': 'text/html; charset=utf-8',
        'x-cache': 'MISS',
      },
    })
  })
  .page('/', async () => {
    return (
      <div>
        <h1>Home</h1>
      </div>
    )
  })

export default {
  fetch(request: Request) {
    return app.handle(request)
  },
}

12/*
  Access-Control-Allow-Origin: *

123export const app = new Spiceflow()
  .staticPage('/about', async () => <About />) // prerendered by `vite build`
  .page('/dashboard', async () => <Dashboard />) // rendered by the Worker per request

123vite build ──► vite preview (built Worker in workerd) ──► GET /about, /about.rsc
                                                            │
dist/client/about.html, about.rsc, _headers  ◄──────────────┘

1spiceflow({ entry: './src/main.tsx', prerenderOrigin: 'https://example.com' })

12345678// wrangler.jsonc
{
  "assets": {
    "binding": "ASSETS",
    // hashed Vite assets still skip the Worker
    "run_worker_first": ["/*", "!/assets/*"]
  }
}

12345678910import { env } from 'cloudflare:workers'
import { Spiceflow } from 'spiceflow'
import { serveAssets } from 'spiceflow/cloudflare'

export const app = new Spiceflow()
  .use(({ request, redirect }) => {
    if (new URL(request.url).pathname === '/about-us') throw redirect('/about')
  })
  .use(serveAssets(env.ASSETS)) // after the middleware that must run first
  .staticPage('/about', async () => <About />)

123GET /about ──► Worker ──► .use() middleware ──► serveAssets ──► env.ASSETS: about.html
                               │                     │
                         redirect / 401        404 ──► render the page in the Worker

1234// wrangler.jsonc
{
  "cache": { "enabled": true }
}

1234567891011import { Spiceflow } from 'spiceflow'

export const app = new Spiceflow()
  .page('/', async ({ response }) => {
    // Fresh for 5 min; serve stale for up to 1 hour while refreshing
    response.headers.set(
      'Cache-Control',
      'public, max-age=300, stale-while-revalidate=3600',
    )
    return <div>Cached at the edge</div>
  })

12345678910111213export const app = new Spiceflow()
  .route({
    method: 'GET',
    path: '/api/data',
    handler() {
      return new Response(JSON.stringify({ ok: true }), {
        headers: {
          'Content-Type': 'application/json',
          'Cache-Control': 'public, max-age=300, stale-while-revalidate=3600',
        },
      })
    },
  })

1response.headers.set('Vary', 'Accept, Accept-Language')

12345678910111213import { headersCache } from 'spiceflow/cloudflare'

app.use(headersCache({
  // Custom cache eligibility check
  shouldCache: (request, response) => response.status === 200,

  // Custom cache key (must be an absolute URL string or Request)
  cacheKey: (request) => {
    const url = new URL(request.url)
    url.search = '' // ignore query params
    return url.toString()
  },
}))