Node.js
Node.js is the only runtime that needs an adapter. Node's HTTP server uses IncomingMessage/ServerResponse, not the standard Request/Response APIs. Juice ships the adapter as @cmj/juice/node, so your server entry is a few lines.
Server Entry
createNodeHandler(manifest, options?) returns an http.createServer request listener that serves your app:
// server.ts
import { createServer } from 'node:http';
import { createNodeHandler } from '@cmj/juice/node';
import manifest from './flight-manifest.json';
const PORT = Number(process.env.PORT ?? 3000);
createServer(createNodeHandler(manifest)).listen(PORT, () => {
console.log(`Listening on http://localhost:${PORT}`);
});This is what create-juice-app --target node scaffolds. Router options go in options.router; the adapter's own options cover the parts of the bridge that apps used to hand-write:
createServer(
createNodeHandler(manifest, {
// Larger request bodies are answered 413 (default: 10 MiB).
maxBodySize: 10 * 1024 * 1024,
// Client chunks and CSS built by `vite build`, served under /assets/
// (default: dist/client, relative to the working directory).
// Pass false when a CDN or reverse proxy serves them instead.
assets: 'dist/client',
// createRouter() options.
router: {
csrfProtection: { allowedOrigins: ['https://admin.example.com'] },
},
}),
).listen(PORT);| Option | Default | What it does |
|---|---|---|
router | {} | Passed to createRouter(). Its requestLimits.maxBodySize defaults to the adapter's maxBodySize, so both layers agree on the limit. |
maxBodySize | 10 MiB | Requests that declare or send a larger body get a 413 Payload Too Large before the router runs, and the connection is closed. |
assets | 'dist/client' | Directory served under /assets/ with Cache-Control: public, max-age=31536000, immutable and a content type from the extension. Paths that escape the directory fall through to the router. false disables it. |
What the Adapter Does
Every request goes through the same four steps:
- IncomingMessage to Request. The
URLis built fromreq.urland theHostheader (httpswhen the socket is TLS). The raw header pairs are copied into aHeadersobject, so repeated headers keep their values. The body is buffered up tomaxBodySizeand passed to theRequest. - Client disconnect to AbortSignal. Node reports a closed connection as the
'close'event on the response. The adapter aborts the request's signal from it, soreq.signalis howeventStream()and streaming renders learn that the client left. - Response to ServerResponse. Status and headers are written with
res.writeHead(status, [...headers].flat()), which keeps everySet-Cookieheader (Object.fromEntrieswould keep only the last). The body is piped withstream.pipeline(), which also cancels the body stream when the client goes away. - Static assets.
GETandHEADrequests under/assets/are served from theassetsdirectory with immutable cache headers. Anything else, and any asset that does not exist, goes to the router.
If you need something the adapter does not do -- WebSocket upgrades, a different static file layout -- attach it to the same http.Server. The WebSockets guide shows the pattern. The adapter is about 200 lines in @cmj/juice/node if you would rather read it than trust it.
Build and Run
juice build produces dist/server.js (CommonJS or ESM depending on your tsconfig):
juice build
node dist/server.jsFor TypeScript development without a build step, use Node 22's built-in TypeScript support:
node --experimental-strip-types server.tsWhy Node.js Needs an Adapter
Node's http module was designed in 2009. It uses IncomingMessage and ServerResponse -- stream-based objects from a pre-fetch() era.
The WinterCG standard (used by Workers, Bun, and Deno) uses Request and Response -- the same APIs the browser provides via fetch(). These were standardized in 2015.
@cmj/juice/node bridges the gap once, so every Node app does not carry its own copy. Every other runtime Juice supports -- Cloudflare Workers, Bun, and Deno -- accepts a fetch handler natively.
Environment Variables
Access environment variables through process.env:
const dbUrl = process.env.DATABASE_URL;For .env file support, use Node 20's --env-file flag:
node --env-file=.env dist/server.jsOn older Node versions, use the dotenv package:
import 'dotenv/config';
// process.env.DATABASE_URL is now availableDocker
A multi-stage Dockerfile for smaller production images:
# Build stage
FROM node:22-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npx juice build
# Production stage
FROM node:22-slim
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/package.json ./
EXPOSE 3000
CMD ["node", "dist/server.js"]The multi-stage build keeps the final image lean by excluding source files, dev dependencies, and build tooling.
Process Managers
PM2
npm install -g pm2
pm2 start dist/server.js --name my-juice-app
pm2 savesystemd
A systemd service file for running Juice in production on Linux:
# /etc/systemd/system/juice-app.service
[Unit]
Description=Juice App
After=network.target
[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/my-juice-app
ExecStart=/usr/bin/node dist/server.js
Restart=on-failure
Environment=NODE_ENV=production
EnvironmentFile=/opt/my-juice-app/.env
[Install]
WantedBy=multi-user.targetsudo systemctl enable juice-app
sudo systemctl start juice-appFor production workloads, consider using Bun instead -- the same code runs with better performance and no process manager needed for automatic restarts (Bun's built-in --watch handles it in development).
When to Use Node.js
- Existing infrastructure requires it. Your deployment platform only supports Node.js, or your CI/CD pipeline is built around it.
- Native Node.js addons. Libraries like
sharp(image processing),bcrypt(password hashing), orcanvas(server-side rendering) use native C++ addons that only work on Node.js. - Node-specific library compatibility. Some libraries depend on Node-specific APIs that other runtimes do not fully implement.
- For everything else -- prefer Bun (faster, same API surface) or Cloudflare Workers (edge deployment, smallest bundle).