Cloudflare Workers

A VitNode Single App builds into one Cloudflare Worker: the site, the Hono API at /api/*, and a Durable Object, the realtime hub, that owns every WebSocket. Pages and the API run at the edge, and Postgres stays where it is, reached over TCP.

What works, and what does notCopy Anchor Link

Before you beginCopy Anchor Link

• A Single App, the one layout create-vitnode-app offers for Workers.
• Workers Paid. A VitNode Worker is above the 3 MiB limit of the Free plan; Shrink the Worker keeps it under the 10 MiB Paid limit.
• A PostgreSQL database that Cloudflare can reach over TCP. A Worker only trusts certificates from a public CA, so a provider such as Supabase needs Hyperdrive.
• Wrangler 4 in the app:

bun add -d wrangler

A new app gets the first three steps below from the generator: answer Cloudflare Workers to "Where do you want to deploy?", or pass --deploy cloudflare. Follow them to convert an existing Single App.

Deploy itCopy Anchor Link

const config = defineConfig(({ command }) => ({
  plugins: [
    vitnode({
      appRoot: import.meta.dirname,
      nitro: command === 'build' ? { preset: 'cloudflare-module' } : {}, 
      webSocket: { transport: 'cloudflare' }, 
    }),
    tailwindcss(),
    tanstackStart(),
    viteReact(),
  ],
}))

{
  "name": "my-vitnode-app",
  "compatibility_date": "2026-10-01",
  "compatibility_flags": ["nodejs_compat"],
  "durable_objects": {
    "bindings": [
      { "name": "VITNODE_REALTIME", "class_name": "VitNodeRealtimeHub" },
    ],
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["VitNodeRealtimeHub"] }],
  "vars": { "VITNODE_INSTALLATION_ID": "default" },
}

import { scopedDatabase } from '@vitnode/core/cloudflare/database'
import { coreRelations } from '@vitnode/core/database/relations'
import { drizzle } from 'drizzle-orm/postgres-js'

export const vitNodeApiConfig = buildApiConfig({
  dbProvider: scopedDatabase(() =>
    drizzle({
      connection: {
        url: process.env.POSTGRES_URL,
        max: 5,
        max_pipeline: 1,
      },
      relations: coreRelations,
    }),
  ),
  // ...the rest of your config
})

POSTGRES_URL=postgresql://user:password@127.0.0.1:5432/vitnode
VITNODE_WEB_URL=http://localhost:8787
CRON_SECRET=a-long-random-string

npx wrangler dev

npx wrangler secret put POSTGRES_URL
npx wrangler secret put VITNODE_WEB_URL
npx wrangler secret put CRON_SECRET

POSTGRES_URL="postgresql://…" bun run db:migrate

npx wrangler deploy --dry-run --outdir .output/wrangler-dry-run
npx wrangler deploy

Connect through HyperdriveCopy Anchor Link

A Worker opens its own TLS connection to POSTGRES_URL and only accepts a certificate signed by a public CA. Supabase signs its database certificates with its own CA, so every API request fails with TLS_HANDSHAKE_FAILED. Hyperdrive is Cloudflare's database proxy: it opens that connection for the Worker and pools it across requests.

Create a Hyperdrive config from your app's folder. For Supabase, use the Direct connection string, not a pooler one, because Hyperdrive does the pooling:

npx wrangler hyperdrive create vitnode --connection-string="postgresql://postgres:password@db.your-project.supabase.co:5432/postgres"

Add the id it prints to wrangler.jsonc:

"hyperdrive": [{ "binding": "HYPERDRIVE", "id": "your-hyperdrive-id" }],

scopedDatabase passes the Worker's bindings to its callback as env, and hyperdriveConnectionString(env) returns the binding's connection string, or undefined on Node and in a Worker without the binding. Fall back to POSTGRES_URL, so vite dev and db:migrate keep using it:

import {
  hyperdriveConnectionString,
  scopedDatabase,
} from '@vitnode/core/cloudflare/database'

dbProvider: scopedDatabase(({ env }) =>
  drizzle({
    connection: {
      url: hyperdriveConnectionString(env) ?? process.env.POSTGRES_URL,
      max: 5,
      max_pipeline: 1,
    },
    relations: coreRelations,
  }),
),

For npx wrangler dev, give the binding a local database in your shell, so the credentials stay out of wrangler.jsonc:

export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgresql://user:password@127.0.0.1:5432/vitnode"
npx wrangler dev

Pass the binding's name as the second argument, hyperdriveConnectionString(env, 'DATABASE'), if you named it something else.

Shrink the WorkerCopy Anchor Link

By default Wrangler uploads every module the build wrote, including chunks nothing imports, without minifying them. A large app, with many plugins or compiled docs, can pass the 10 MiB Paid limit that way. Let Wrangler bundle from the entry and minify:

"no_bundle": false,
"minify": true,
"keep_names": false,
"upload_source_maps": false,

The VitNode website went from 13.1 MiB to 6.6 MiB gzipped. Keep keep_names off: some server code sends functions to the browser as source text (the theme and scroll restoration scripts), and esbuild's name-keeping helper turns them into calls to a function the browser does not have, so every page the Worker renders fails with n is not defined. Turn upload_source_maps off too: a real deploy uploads the bundle's source maps unless told not to, and a large app's maps pass Cloudflare's 60 MiB limit (error 10021), which a dry run does not check.

If the app prerenders pages, also set "assets": { "html_handling": "drop-trailing-slash" }. A prerendered page is written as page/index.html, and Cloudflare otherwise redirects /page to /page/.

Check the resultCopy Anchor Link

With npx wrangler dev running, http://localhost:8787/api/health/ready answers 200 with {"status":"ok"}. If it answers 503, the Worker cannot reach POSTGRES_URL. wrangler deploy --dry-run prints the Worker's size as Total Upload: … / gzip: …. To check WebSockets end to end, follow Cloudflare WebSockets.

TroubleshootingCopy Anchor Link

RelatedCopy Anchor Link