If npm start runs it, we run it.
Express, Hono, Fastify, a server-rendered site, a small API. One start script and you’re done — there is nothing else to configure.
You need a start script.
npm start is the entrypoint. Without a start script in package.json there is nothing to run, and the app won’t come up — this is the single most common Node failure.
A build script runs automatically before start when it exists, and is skipped when it doesn’t. That’s where TypeScript compilation or a frontend bundle belongs.
Listen on the port we give you — process.env.PORT. There is no port setting on our side, so an app hardcoded to 3000 is a coin flip. Your agent knows this convention.
{
"name": "my-api",
"scripts": {
"build": "tsc",
"start": "node dist/server.js"
},
"dependencies": {
"hono": "^4.6.0"
}
}Everything the platform expects.
Four facts, and they are the complete set — there is nothing else to get right.
package.json at the root of what you sendnpm start — your build script runs first, if you have onepackage.json, using your lockfile when you include one. Don’t send node_modules.- build commands
- start commands
- ports
- Dockerfiles
- nginx
- systemd
- process managers
You configure none of this.
There is no build command, no start command and no port setting — for any runtime. Your agent sends files; what runs them is worked out from what's inside.
- TLS renewal
- health checks
- restart policies
- log rotation
- scaling rules
- deploy hooks
- CI pipelines
The one thing each runtime does expect is its entrypoint, and that’s on this page. The deploy reference is the exhaustive version your agent reads.
Will it run what you built?
We'd rather you found out here than mid-deploy, so both halves get the same billing.
Yes — what people deploy here
Express, Hono, Fastify and Koa APIs · server-rendered sites · webhook receivers · small back-ends for a static front-end · Discord and Slack bots with an HTTP endpoint · anything that binds a port and answers HTTP
No — what doesn’t work
Long-running background work that isn’t tied to a request, and anything expecting to keep state on local disk between deploys — the filesystem is not persistent, so anything that has to survive a deploy belongs in the database that comes with your app. WebSockets and long polling are fine.
Why a deploy doesn't come up.
Your agent will usually get these right, and can read the logs when it doesn't. Listed anyway, because knowing the shape of the failure makes the log message make sense.
No start script.
A package.json with only dev and build leaves nothing to launch. dev is not used — add a real start.
A hardcoded port.
app.listen(3000) ignores the port assigned to your app. Use process.env.PORT, falling back to a local default if you like.
node_modules included.
Sending installed dependencies makes the upload enormous and can carry binaries built for your laptop rather than for the server. Send package.json and the lockfile; the install happens here.
Dev dependencies needed at runtime.
If your start command reaches for something listed under devDependencies, it may not be there. Anything the running app needs belongs in dependencies.
Not what you're building?
Point your agent at it.
€4 a month, database included. Your agent reads the deploy reference itself, so you don't have to.