@photonjs/cloudflare

Cloudflare Workers and Pages adapter for Photon, enabling deployment of universal web applications to Cloudflare's edge network.

Overview

This adapter provides seamless integration between Photon and Cloudflare's runtime environments:
- Cloudflare Workers: Deploy server functions to Cloudflare's edge network
- Cloudflare Pages: Static site hosting with edge functions
- Workerd Runtime: Local development with Cloudflare's runtime
- WebSocket Support: Real-time applications with crossws integration
- H3 Integration: Built-in support for H3 server framework

Installation

``bash
npm install @photonjs/cloudflare


or

pnpm add @photonjs/cloudflare

or

yarn add @photonjs/cloudflare
`

Usage

$3

Add the Cloudflare adapter to your Vite configuration:

`ts
// vite.config.ts
import { installPhoton } from '@photonjs/runtime/vite'
import { cloudflare } from '@photonjs/cloudflare/vite'

export default {
plugins: [
installPhoton({
// optional
server: './src/server.ts'
}),
cloudflare()
]
}
`

$3

Configure Wrangler to use your Photon's virtual entry:

`toml


wrangler.toml


name = "my-photon-app"
main = "virtual:photon:cloudflare:server-entry"
compatibility_date = "2025-08-28"
`

$3

#### With Hono

`ts
// src/server.ts
import { Hono } from 'hono'
import { apply, serve } from '@photonjs/hono'

const app = new Hono()

app.get('/', (c) => c.text('Hello from Photon + Hono on Cloudflare!'))

apply(app)
export default serve(app)
`

#### With H3

`ts
// src/server.ts
import { createApp, defineEventHandler } from 'h3'
import { apply, serve } from '@photonjs/h3'

const app = createApp()

app.use('/', defineEventHandler(() => 'Hello from Photon + H3 on Cloudflare!'))

apply(app)
export default serve(app)
`

API Reference

$3

- ./vite - Vite plugin for Cloudflare integration
- ./hono - Hono-specific Cloudflare utilities
- ./h3 - H3-specific Cloudflare utilities
- ./srvx - srvx-specific Cloudflare utilities
- ./dev - Development server utilities
- ./virtual - TypeScript declarations for virtual modules

$3

#### asFetch(app): ExportedHandlerFetchHandler

Converts a Hono app to a Cloudflare Workers fetch handler:

`ts
import { asFetch } from '@photonjs/cloudflare/hono'
import { Hono } from 'hono'

const app = new Hono()
export default { fetch: asFetch(app) }
`

Development

$3

`bash


Development with Cloudflare's workerd runtime

npm run dev:cloudflare

or

pnpm dev:cloudflare
`

$3

`bash


Build for Cloudflare deployment

npm run build:cloudflare

or

pnpm build:cloudflare
`

Environment Variables

Access Cloudflare environment variables and bindings:

`ts
// In your handlers
export default {
async fetch(request, env, ctx) {
// env contains your Cloudflare bindings
const value = env.MY_KV_NAMESPACE.get('key')
// ...
}
}
`

WebSocket Support

Enable WebSocket support with crossws:

`bash
npm install crossws
`

`ts
// vite.config.ts
export default {
plugins: [
photon({
server: './src/server.ts'
}),
cloudflare({
// WebSocket support will be automatically detected
})
]
}
`

Examples

See the example applications:
- Basic Cloudflare App
- Hono + Cloudflare App

Deployment

$3

`bash


Deploy to Cloudflare Workers

wrangler deploy

Deploy to Cloudflare Pages

wrangler pages deploy dist
`

$3

`yaml


.github/workflows/deploy.yml

name: Deploy to Cloudflare
on:
push:
branches: [main]

jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
- run: npm install
- run: npm run build:cloudflare
- uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
``

License

MIT