Deploy guide · runtime = "node"

Deploy Node.js on Percher

Vanilla Node.js HTTP server with no framework. The runtime is Node 24 on a slim Alpine image. Use this when you want full control over the request pipeline or are running a small custom server without Express/Fastify overhead.

Why Percher fits

• Percher's node-build pipeline ships a multi-stage Dockerfile that produces a ~225 MB image and runs `node` directly — no extra layer between your code and the runtime.
• Deps are cached aggressively: redeploys with unchanged `package.json` skip the install step and finish in ~10 s.

Quick start

bunx percher create my-app --template node
cd my-app
bunx percher publish

The first command scaffolds a working Node.js project plus a `percher.toml`. Publish builds and deploys it; the live URL prints on completion.

percher.toml

The canonical config for a Node.js app on Percher. `bunx percher init` generates this automatically when it detects Node.js in your project.

[app]
name = "my-server"
runtime = "node"

[web]
port = 3000
health = "/health"

Common gotchas

• Your server must listen on `process.env.PORT` (or `3000` if missing) — Percher passes the port at runtime and the value can change between deploys.
• Add a `GET /health` route that returns 200; without it the deploy health check fails and the new version is never swapped in.

Related docs

• Quick start →
• Recommended setup →

Ready to deploy Node.js?

Free plan, no credit card. Live in under a minute.