|
| 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