Deploy Node.js, Next.js and Nuxt

This guide deploys a server-rendered JavaScript or TypeScript app — Express, Fastify, Hono, NestJS, Next.js, Nuxt, Remix, SvelteKit, Astro SSR — to Falak. The app runs as a supervised process on each server, and Caddy terminates TLS and proxies to it.

Prerequisites

• A server of type app, web or worker with Node.js (the default server stack installs Node 22).
• A package.json with:
  • a start script — Falak runs npm run start in the release;
  • a build script if your app needs one (Next.js, Nuxt, TypeScript).
• Your app listens on process.env.PORT (and ideally process.env.HOST).

server.js

import http from 'node:http';

const port = Number(process.env.PORT ?? 3000);
const host = process.env.HOST ?? '127.0.0.1';

http.createServer((req, res) => res.end('Hello from Falak')).listen(port, host);

package.json

{
  "scripts": {
    "build": "tsc -p .",
    "start": "node dist/server.js"
  }
}

Deploy

1. + Create → Git repository, choose the repository and branch.
2. Falak detects the stack and suggests Next.js, Nuxt or Generic Node. The runtime is Node.js.
3. Pick servers and a domain, then click Deploy.
4. The build installs dependencies, runs build, prunes dev dependencies and uploads the release. Each server starts the web process and Caddy proxies the domain to it.

How it runs

Aspect	Value
Web process	<slug>.app, supervised by the agent: npm run start in /srv/falak/sites/<slug>/current
Environment	Your site variables + PORT=<app port>, HOST=127.0.0.1, NODE_ENV=production (unless you set it), PATH=/usr/local/bin:/usr/bin:/bin, plus FALAK_SITE, FALAK_SITE_ID, FALAK_SERVER_ID, FALAK_RELEASE_ID, FALAK_DEPLOYMENT_ID
App port	Allocated per server from 3000–3999, shown as app_port on the site
User	The site user (falak by default)
Health check	GET / expecting 200 (change under Settings → Deploy)
Deploy script	$FALAK_FETCH → $FALAK_ACTIVATE → $FALAK_RESTART_PROCS
On deploy	The web process restarts in the new release

Note

The web process always runs npm run start, whatever package manager built the app. npm run works with pnpm and yarn projects because it only runs the script.

Framework notes

Next.js

• Preset variables: NODE_ENV=production, NEXT_TELEMETRY_DISABLED=1.
• Make sure start is next start (it reads PORT automatically).
• Build-time public variables must start with NEXT_PUBLIC_ to reach the build. See Builds.
• APM: add instrumentation.ts with @falak/apm-node/next. See APM for Node.

Nuxt

• Preset variables: NODE_ENV=production, NITRO_PRESET=node-server.
• start should run the Nitro server: node .output/server/index.mjs.
• Public runtime config variables start with NUXT_PUBLIC_.

Express, Fastify, Hono, NestJS

• Use the Generic Node preset.
• Listen on PORT. Bind to HOST (127.0.0.1) so the app is only reachable through Caddy.

Astro SSR, SvelteKit, Remix

• Use the Node adapter (@astrojs/node, @sveltejs/adapter-node, Remix’s Node server) and a start script that runs the built server.
• Without an SSR adapter, Astro and Vite apps are static sites.

Workers and cron

Add background processes (node worker.js, BullMQ consumers) as daemons and scheduled scripts as cron jobs in the Processes tab. See Processes.

Node.js versions

Servers offer Node 20 (20.19.5), 22 (22.20.0, default) and 24 (24.9.0). The builder reads your project’s Node version. Pick the site’s Node version in Settings → Build. Sites can select 18, 20, 22 or 24; make sure the server has that version installed.

Troubleshooting

Symptom	Cause and fix
Health check fails, logs say Missing script: "start"	Add a start script to package.json.
502 from the domain	The app does not listen on PORT, or crashed. Check the site’s Logs tab.
EADDRINUSE	You hard-coded a port. Use process.env.PORT.
Build fails with a lockfile error	Commit your lockfile, or override the install with FALAK_INSTALL_COMMAND.
Environment variable undefined in the browser bundle	Build-time variables need a public prefix (NEXT_PUBLIC_, VITE_, …) or must be exposed to the deploy script.

Next steps

BunRun TypeScript directly with Bun.

MonoreposCustom install and build commands.