Skip to content

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);
OptionDefaultWhat it does
router{}Passed to createRouter(). Its requestLimits.maxBodySize defaults to the adapter's maxBodySize, so both layers agree on the limit.
maxBodySize10 MiBRequests 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:

  1. IncomingMessage to Request. The URL is built from req.url and the Host header (https when the socket is TLS). The raw header pairs are copied into a Headers object, so repeated headers keep their values. The body is buffered up to maxBodySize and passed to the Request.
  2. 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, so req.signal is how eventStream() and streaming renders learn that the client left.
  3. Response to ServerResponse. Status and headers are written with res.writeHead(status, [...headers].flat()), which keeps every Set-Cookie header (Object.fromEntries would keep only the last). The body is piped with stream.pipeline(), which also cancels the body stream when the client goes away.
  4. Static assets. GET and HEAD requests under /assets/ are served from the assets directory 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.js

For TypeScript development without a build step, use Node 22's built-in TypeScript support:

node --experimental-strip-types server.ts

Why 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.js

On older Node versions, use the dotenv package:

import 'dotenv/config';
// process.env.DATABASE_URL is now available

Docker

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 save

systemd

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.target
sudo systemctl enable juice-app
sudo systemctl start juice-app

For 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), or canvas (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).