Node.js pack - Nubo Docs

The Node pack covers anything driven by a package.json: REST APIs, Discord bots, Express servers, Next.js (non-SSR builds), the lot. It auto-picks your package manager from the lockfile.

When it runs

There’s a package.json at the repo root.

Package manager detection

Raypacks reads your lockfile to decide what to install with:

Lockfile	Manager	Base image
`bun.lockb` or `bun.lock`	bun	`oven/bun:slim`
`pnpm-lock.yaml`	pnpm	`node:22-slim`
`yarn.lock`	yarn	`node:22-slim`
(none of the above)	npm	`node:22-slim`

Commit your lockfile. Without it Raypacks falls back to npm.

Build steps

For every Node project:

<pm> install           # ci for npm, --frozen-lockfile for pnpm/yarn
<pm> run build         # only if package.json has a "build" script

If you don’t have a build script (a bare API or bot), only the install step runs.

Command overrides

Most projects need nothing here: Raypacks picks the install and build steps from your lockfile and package.json. For a project that doesn’t fit the defaults, a Frame exposes Install command and Build command overrides in Frame Settings, under Build. Set either one to replace the auto-detected step (for example a custom install flag, or a build script that isn’t named build); the build command runs after install. Leave them blank to let Raypacks pick.

Runtime

pm	Entrypoint
bun	`bun run start`
anything else	`npm start` if you have a `start` script, otherwise `node <package.json#main>`, otherwise `node index.js`

Field	Value
Working dir	`/app`
Port	from Frame settings, default 3000
Env	`NODE_ENV=production`, `PORT=<your port>`

Your start script is the contract Raypacks expects. Define one and the pack lights up:

package.json

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

Limits today

No engines.node enforcement (we ship node:22-slim regardless).
Workspaces (pnpm-workspace.yaml, npm workspaces) build everything but the root scripts run.

Common errors

App starts and exits immediately: your start script ran something that wasn’t a long-running server. Make sure it boots an HTTP listener. Port mismatch: your app listens on process.env.PORT but you set the Frame port to something else. Read PORT from env, don’t hardcode. Native modules fail to build: node:22-slim doesn’t include build toolchains. For now, prefer prebuilt binaries (better-sqlite3 with prebuilt, etc.) or switch to the Paketo builder.

​When it runs

​Package manager detection

​Build steps

​Command overrides

​Runtime

​Limits today

​Common errors