NODE DEPLOYMENT
How to deploy a Node application
Deploy a Node web app or API with a compatible Node 22 runtime, production start command, PORT binding, and health checks.
DIRECT ANSWER
The short version
To deploy a Node application, make sure it has a production start path and listens on the PORT environment variable at 0.0.0.0. Ample detects common Node projects, installs dependencies, runs the build when present, selects a Node 22 runtime for a new server, and waits for the app to pass health checks.
WHO THIS IS FOR
Before you start
This guide is for Node, Express, Fastify, and other JavaScript server projects that need a public URL.
STEP BY STEP
How to do it
-
1
Define a production start command
The process should start the actual web server, not a file watcher or development server. Put the command in package.json or provide it explicitly.
-
2
Bind to the platform port
Read process.env.PORT, fall back only for local use, and listen on 0.0.0.0 so the platform can reach the process.
server.listen(Number(process.env.PORT || 3000), '0.0.0.0') -
3
Run the plan
The plan can detect linked databases, required secrets, and whether the repo contains multiple services.
ample plan --write -
4
Deploy and inspect the result
Apply the plan. If activation fails, use runtime logs to inspect the process output rather than rerunning the same deployment.
ample up
FIT CHECK
What this supports
Good fit
- Node 22 applications
- Express and Fastify APIs
- npm, pnpm, yarn, and bun dependency workflows
- Linked managed databases and persistent volumes
Know the limits
- Development-only start commands are not suitable for production
- A Node app must use a Node-compatible server template
- Local disk writes need a volume if they must survive releases
TROUBLESHOOTING
Common failure modes
Health checks cannot connect
Bind the process to 0.0.0.0 and the supplied PORT.
The process exits immediately
Read runtime logs and verify the production start file exists in the packaged release.
A native or workspace dependency is missing
Check the lockfile, deploy root, install command, and build output in the build logs.