Deploy

Deploying Routa is compiling to dist/ and running routa start. The one setting that almost always needs changing is the host: Routa binds to 127.0.0.1 by default, which is correct for local development and wrong inside a container.

Before You Start

• A project that passes routa check.
• Node.js 24 or later in the runtime environment.
• Knowing whether your platform assigns a port through PORT.

Steps

1. Build. Validation runs first, so a contract error stops the deploy before it produces an artifact.

   npm

   npm run build

   pnpm

   pnpm run build

   yarn

   yarn run build

   bun

   bun run build

2. Bind to all interfaces. Set HOST in the environment rather than in src/routa.ts, so local development keeps its safe default.

   npm

   HOST=0.0.0.0 npm run start

   pnpm

   HOST=0.0.0.0 pnpm run start

   yarn

   HOST=0.0.0.0 yarn run start

   bun

   HOST=0.0.0.0 bun run start

3. Accept a platform-assigned port when your host provides one.

   Leave PORT unset so the platform can inject its assigned value. For example, if the platform supplies PORT=8080, start with only the host override:

   npm

   HOST=0.0.0.0 npm run start

   pnpm

   HOST=0.0.0.0 pnpm run start

   yarn

   HOST=0.0.0.0 yarn run start

   bun

   HOST=0.0.0.0 bun run start

Verify

The start log confirms the bound address:

[2026-01-01T00:00:00.000Z] INFO api.started Routa API started. {"host":"0.0.0.0","port":8080,"routes":4}

What the Runtime Image Needs

routa start reads compiled JavaScript from dist/, but it still validates the route graph from source before starting. Keep all four in the image:

Path	Why
src/	Route validation reads the TypeScript source
.routa/	Route metadata and the baseline used by validation
dist/	The JavaScript that actually runs
node_modules/	Production dependencies, including @routa-ts/cli

This is also why generated apps keep @routa-ts/cli in dependencies rather than devDependencies.

Container Shape

Use a build stage to install every dependency and run the build, then copy source, metadata, output, and production dependencies into the runtime stage:

Dockerfile

FROM node:24-slim AS build
WORKDIR /app
COPY . .
RUN npm ci && npm run build

FROM node:24-slim
WORKDIR /app
ENV HOST=0.0.0.0
COPY --from=build /app/package.json ./package.json
COPY --from=build /app/src ./src
COPY --from=build /app/.routa ./.routa
COPY --from=build /app/dist ./dist
RUN npm ci --omit=dev
CMD ["npm", "run", "start"]

Configuration Precedence

Environment variables win over src/routa.ts, which wins over Routa’s defaults:

Setting	Environment	Config	Default
Host	HOST	host	127.0.0.1
Port	PORT	port	3000

Troubleshooting

Problem	Fix
Health checks fail although the container is running	The server bound to 127.0.0.1. Set HOST=0.0.0.0.
Missing compiled runtime output for … Run routa build first.	dist/ was not copied into the runtime stage, or the build stage was skipped.
Compiled runtime output for … is stale.	Source files were copied after the build. Copy src/ and dist/ from the same stage.
ROUTA_PROJECT_REQUIRED at startup	src/ or src/routa.ts is missing from the image. Validation needs the source.

v0 status

Production builds and routa start are implemented in v0 for Node.js deployments. routa dev compiles on the fly and supervises restarts, so use routa build at image build time and routa start as the container command.

Next Steps

ConfigurationEvery option and environment variable Routa reads.

Run and startHow start differs from dev.

API evolutionGate deploys on contract compatibility.