Skip to content

Commit f0cab66

Browse files
committed
feat: Cloudflare Workers realtime, Bun and Docker deploy targets, health checks
- ws: instance-owned registry and a realtime runtime (ALS scope) behind the unchanged `wsRegistry`/`realtime` facades; shared handshake lifecycle. - Cloudflare: one Durable Object realtime hub per installation (`@vitnode/core/cloudflare/{hub,edge,database}`), Hibernation API with SQLite room storage, optional sharding (`VITNODE_REALTIME_SHARDS`), `scopedDatabase`, `runWithVitNodeCloudflare`, and `vitnode({ webSocket: { transport: "cloudflare" } })`. - create-vitnode-app: "Where to deploy?" (Node.js, Bun, Cloudflare Workers), a Cloudflare overlay, a Bun target (Nitro `bun` preset, Hono on `Bun.serve`), `vitnode.runtime` in package.json, and a production Docker image (`Dockerfile`, `.dockerignore`, `docker-compose.prod.yml`). - Starter template: typed app messages and `HrefLink` (23 type errors and the lint OOM fixed); root route declares `loader` before `head`. The API template's runtime imports (`@hono/node-server`, `dotenv`, `lucide-react`) are dependencies. - Core: `GET /api/health` and `GET /api/health/ready`. - CLI: `vitnode start` runs `bun`-preset builds on Bun; the runtime follows `vitnode.runtime`; the build hint names `preview:cloudflare`. - apps/web: `pnpm build:cloudflare` deploys it as one Worker (bundled and minified to 6.6 MiB gzipped); `apps/cloudflare` fixture removed in favour of `scripts/cloudflare-smoke`. - Wrangler runs from the app folder, so `.dev.vars` loads. - `workerd`'s install script is declared in `allowBuilds`. - Docs: Cloudflare WebSockets, Deployments > Cloud > Cloudflare Workers, Docker, Bun and Health checks pages, plus setup, CLI and contribution updates. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CnAiFZHQw1SaeJbt11brzs
1 parent 6f1791c commit f0cab66

75 files changed

Lines changed: 7086 additions & 1170 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎apps/web/.dev.vars.example‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Secrets for `pnpm preview:cloudflare` (wrangler dev). Copy to `.dev.vars`;
2+
# never commit it. In production set each with `wrangler secret put <NAME>`.
3+
POSTGRES_URL=postgresql://root:root@127.0.0.1:5432/vitnode
4+
VITNODE_WEB_URL=http://localhost:8787
5+
CRON_SECRET=your-secure-cron-secret-key
6+
# Optional
7+
SUPABASE_URL=
8+
SUPABASE_SECRET_KEY=
9+
SUPABASE_STORAGE_BUCKET=
10+
STRIPE_SECRET_KEY=
11+
STRIPE_WEBHOOK_SECRET=

‎apps/web/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ dist-ssr
55
*.local
66
.env*
77
!.env.example
8+
.dev.vars*
9+
!.dev.vars.example
810
.nitro
911
.tanstack
1012
.wrangler

‎apps/web/content/docs/dev/cli/build.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -135,7 +135,7 @@ vitnode start
135135

136136
| Project | Entry it runs | Default port |
137137
| -------------- | ----------------------------------------------------------------- | ------------ |
138-
| App | Nitro's server entry, usually `.output/server/index.mjs`, on Node | `3000` |
138+
| App | Nitro's server entry, usually `.output/server/index.mjs`, on Node - or on Bun when it was built with Nitro's `bun` preset | `3000` |
139139
| API app (Node) | `dist/index.js` on Node | `8000` |
140140
| API app (Bun) | `src/index.ts` on Bun | `8000` |
141141

‎apps/web/content/docs/dev/cli/dev.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,7 @@ The port is `--port`, then `PORT`, then `8000`. The CLI passes it to your API as
8585

8686
The API runs on Bun, with `bun --hot`, when any of these is true:
8787

88+
- `package.json` declares `"vitnode": { "runtime": "bun" }` (`"node"` there forces Node, whatever else says Bun)
8889
- you started the script with Bun (`bun run dev`)
8990
- the nearest `packageManager` field says `bun@...`
9091
- the nearest lockfile is `bun.lock` or `bun.lockb`

‎apps/web/content/docs/dev/contribution.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,18 @@ Open `http://localhost:3000` for the website, the AdminCP at `/admin` and the li
6767
| `apps/api` | The standalone Hono API server |
6868
| `plugins/*` | First-party plugins (`@vitnode/blog`, `@vitnode/forum`, `newsroom`) |
6969

70+
### Deploy the website to Cloudflare
71+
72+
`apps/web` builds for Node by default. `pnpm build:cloudflare` builds the same app as one Cloudflare Worker - site, API and realtime hub - with the settings in `apps/web/wrangler.jsonc`. Build the CLI and plugins first, as in [Run the checks](#run-the-checks), then from `apps/web`:
73+
74+
```bash
75+
pnpm build:cloudflare
76+
pnpm preview:cloudflare # local workerd, reads .dev.vars (copy .dev.vars.example)
77+
pnpm deploy:cloudflare
78+
```
79+
80+
Set `POSTGRES_URL`, `VITNODE_WEB_URL` and `CRON_SECRET` once with `npx wrangler secret put <NAME>`, plus the Supabase and Stripe keys the site uses. Leave `REDIS_URL` unset. Run migrations from your machine or CI with `pnpm --filter api db:migrate` against the production database before each deploy. Images are stored as uploaded on Workers, because re-encoding needs `sharp`. [Cloudflare Workers](/docs/dev/deployments/cloud/cloudflare) explains the Worker itself.
81+
7082
## Run the checks
7183

7284
Before opening a pull request, run what GitHub Actions runs, from the repository root:
Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
title: Bun
3+
description: Develop, build and run a VitNode app or API on Bun instead of Node.js - TanStack Start through Nitro's bun preset, and Hono on Bun.serve.
4+
icon: Zap
5+
---
6+
7+
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
8+
9+
VitNode runs on [Bun](https://bun.com) from the first `dev` to production. The TanStack Start app runs Vite on Bun and builds with Nitro's `bun` preset, and a standalone Hono API runs its TypeScript straight on `Bun.serve` - no compile step. Same app, same plugins, one runtime fewer to install on the server.
10+
11+
## Before you begin
12+
13+
- [Bun](https://bun.com/docs/installation) installed on your machine and on the server. Node.js is optional: when it is missing, `bun run` stands in for it, so the `vitnode` CLI still runs.
14+
- A PostgreSQL database, as for any VitNode deployment.
15+
16+
## Create a Bun app
17+
18+
Answer **Bun** to "Where to deploy?" when you create the app. The option shows up only when Bun is installed, and it is the default when you pick Bun as the package manager.
19+
20+
<Tabs groupId="package-manager" persist items={["bun", "pnpm", "npm"]} label="Create a Bun app">
21+
22+
```bash tab="bun"
23+
bun create vitnode-app@canary --deploy bun
24+
```
25+
26+
```bash tab="pnpm"
27+
pnpm create vitnode-app@canary --deploy bun
28+
```
29+
30+
```bash tab="npm"
31+
npx create-vitnode-app@canary --deploy bun
32+
```
33+
34+
</Tabs>
35+
36+
Any package manager can install the packages; the runtime is a separate choice. Here is what the generator changes compared with a Node app:
37+
38+
| Where | Node app | Bun app |
39+
| -------------------- | ---------------------------------- | ----------------------------------------------------- |
40+
| App `dev` / `build` | `vitnode dev`, `vitnode build` | `bun --bun vitnode dev`, `bun --bun vitnode build` |
41+
| App `vite.config.ts` | Nitro's default Node server | `nitro: { preset: "bun" }` |
42+
| API entry | `@hono/node-server` and `ws` | `export default { fetch, websocket }` with `hono/bun` |
43+
| API `build` | `tsc` into `dist` | none - Bun runs `src/index.ts` |
44+
| `package.json` | `"vitnode": { "runtime": "node" }` | `"vitnode": { "runtime": "bun" }` |
45+
46+
`start` stays `vitnode start` in both. It reads the build's preset (or the API's `vitnode.runtime`) and starts the server with Bun or Node to match.
47+
48+
## Move an existing app to Bun
49+
50+
<Steps>
51+
<Step>
52+
53+
### Build the app for Bun
54+
55+
Set Nitro's preset in the app's `vite.config.ts`:
56+
57+
```ts title="vite.config.ts (excerpt)"
58+
vitnode({
59+
nitro: {
60+
preset: 'bun',
61+
rollupConfig: { external: [/^@sentry\//] },
62+
},
63+
webSocket: true,
64+
})
65+
```
66+
67+
</Step>
68+
<Step>
69+
70+
### Run Vite on Bun
71+
72+
Prefix the app's `dev` and `build` scripts with `bun --bun`, so Vite and the SSR code run on Bun rather than on Node:
73+
74+
```json title="package.json (excerpt)"
75+
{
76+
"scripts": {
77+
"dev": "bun --bun vitnode dev",
78+
"build": "bun --bun vitnode build",
79+
"start": "vitnode start"
80+
},
81+
"vitnode": { "runtime": "bun" }
82+
}
83+
```
84+
85+
</Step>
86+
<Step>
87+
88+
### Serve a standalone API with Bun
89+
90+
Skip this step for a single app - its API is part of the build above.
91+
92+
A standalone API exports Bun's server object instead of calling `serve` from `@hono/node-server`. Copy the [WebSocket route for Bun](/docs/dev/websocket/setup#on-bun), drop the API's `build` script and set `"vitnode": { "runtime": "bun" }` in its `package.json`. `vitnode dev` then runs `bun --hot src/index.ts` and `vitnode start` runs `bun src/index.ts`. You can remove `@hono/node-server` and add `@types/bun` to `devDependencies`.
93+
94+
</Step>
95+
</Steps>
96+
97+
## Build and run
98+
99+
Deploy exactly as in [Self-hosted](/docs/dev/deployments/self-hosted), with the same four commands:
100+
101+
<Tabs groupId="package-manager" persist items={["bun", "pnpm", "npm"]} label="Deploy on Bun">
102+
103+
```bash tab="bun"
104+
bun install --frozen-lockfile
105+
bun run build
106+
bun run db:migrate
107+
bun start
108+
```
109+
110+
```bash tab="pnpm"
111+
pnpm install --frozen-lockfile
112+
pnpm build
113+
pnpm db:migrate
114+
pnpm start
115+
```
116+
117+
```bash tab="npm"
118+
npm ci
119+
npm run build
120+
npm run db:migrate
121+
npm start
122+
```
123+
124+
</Tabs>
125+
126+
<Callout type="warn" title="Bun reads .env on its own">
127+
Bun loads `.env` before your code starts, so every variable in it applies -
128+
even one you forgot about. A `REDIS_URL` pointing at a Redis that isn't
129+
running makes WebSocket handshakes answer `503` until Redis is up. Comment out
130+
what you don't use.
131+
</Callout>
132+
133+
## Check the result
134+
135+
`vitnode start` prints `Running` once the server accepts connections. To be sure it is Bun answering, list the processes: the server shows up as `bun .output/server/index.mjs` for an app, or `bun src/index.ts` for an API.
136+
137+
## Related
138+
139+
<Cards>
140+
<Card
141+
title="Self-hosted"
142+
description="Environment variables, Nginx and PM2 for any runtime"
143+
href="/docs/dev/deployments/self-hosted"
144+
/>
145+
<Card
146+
title="WebSocket setup"
147+
description="The /api/ws route on Nitro, Node and Bun"
148+
href="/docs/dev/websocket/setup"
149+
/>
150+
<Card
151+
title="Build and start"
152+
description="What vitnode build and vitnode start do"
153+
href="/docs/dev/cli/build"
154+
/>
155+
</Cards>

0 commit comments

Comments
 (0)