App service
Services/Node.js (Next.js)

Node.js (Next.js) service

Runtime service for Next.js applications that need a reusable building block inside a stack.

Use it as a versioned stack building block that can build from source, plug into CI/CD, and connect to external providers without hardcoding secrets into the codebase.

On Wodby

How Node.js (Next.js) runs on Wodby

What Wodby sets up for an application that runs on this service. Check it before changing the start command, the port or connection settings in the code.

How the application is started

The image built by the service's Dockerfile starts the application with npm run start, from /usr/src/app. package.json must define a start script.

  • The application must listen on port 3000, on all interfaces. That is the port of the service's HTTP endpoint. The service sets NODE_PORT to that number; it does not set PORT. Read NODE_PORT, or default to 3000.
  • NODE_ENV is development in environments of type dev and production in every other type.

Build

The service's Dockerfile only copies the build context to /usr/src/app. It does not run npm install. Dependencies, and any compiled output, must be produced by the pipeline before the image is built, for example with wodby ci run -- npm ci, so that node_modules is part of what is copied. An image built without node_modules cannot load the application's dependencies.

A pipeline that passes a Dockerfile from the repository (wodby ci build node -f Dockerfile) uses that file instead.

The service declares no volume of its own: files written inside the container are lost when it is replaced.

Linked services

Links to other services reach the application as environment variables. Nothing in the image reads them: the application reads them itself. Do not hardcode hosts or credentials.

LinkVariables
Database (MariaDB, MySQL or PostgreSQL)DB_HOST, DB_PORT, DB_NAME (also DB_DATABASE), DB_USERNAME, DB_PASSWORD, DB_DRIVER (also DB_CONNECTION)
MailSMTP_HOST, SMTP_PORT
Redis or ValkeyREDIS_HOST, REDIS_PORT, REDIS_PASSWORD
OpenTelemetry CollectorOTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL (http/protobuf), OTEL_EXPORTER_OTLP_HEADERS (the Collector's ingest token)

All links are optional. A variable is present only while its link exists and the linked service is enabled. The mail link carries no credentials. The OpenTelemetry variables are the standard SDK settings: an application or agent that uses an OpenTelemetry SDK exports to the Collector without further configuration; set OTEL_SERVICE_NAME to name the application in traces.

Environment

  • WODBY_HOSTS is a JSON array of the environment's hosts, not a comma-separated string. WODBY_PRIMARY_HOST and WODBY_PRIMARY_URL are the canonical ones for links generated outside a request.
  • WODBY_APP_SERVICE_NAME is this service's host name inside the environment. Other services reach the application at that name on port 3000.
  • WODBY_ENV_TYPE tells a development environment from a production-like one.

In a development workspace

  • The checkout is mounted at /usr/src/app and served as it is on disk.
  • Workspace setup installs dependencies with workspace-node prepare. The package manager is taken from packageManager in package.json, otherwise from the lockfile: pnpm-lock.yaml means pnpm, yarn.lock means Yarn, anything else npm. Installs follow the lockfile exactly (npm ci, --frozen-lockfile, --immutable), with development dependencies. Run it again after changing dependencies.
  • The application is started with the dev script of package.json when there is one, otherwise with start. WORKSPACE_NODE_COMMAND on the service replaces that command.
  • NODE_ENV is always development here, whatever the environment type. PORT is set, to NODE_PORT unless given, and HOST to 0.0.0.0.
  • A saved file is picked up without a restart or a deployment. A dev script is expected to watch the files itself. A start script runs the application once, so the checkout is watched for it: when a file changes, the application is stopped and started again in the same container, within a few seconds. node_modules, .git, .pnpm-store, .next, dist, build and coverage are not watched. A command set with WORKSPACE_NODE_COMMAND is run as it is, without that watcher; WORKSPACE_NODE_WATCH=0 turns the watcher off. For scripts with their own watcher, CHOKIDAR_USEPOLLING, CHOKIDAR_INTERVAL and WATCHPACK_POLLING are set, because a checkout on network storage needs polling. WORKSPACE_POLL_INTERVAL changes the interval, WORKSPACE_POLLING=0 turns this off.
  • node_modules/ and /.pnpm-store/ are kept out of Git status without touching .gitignore.
  • A change to variables or linked services still needs a deployment of the environment.

Check the result

  • curl -s -o /dev/null -w '%{http_code}' "localhost:$NODE_PORT" from the container shows whether the application answers on the expected port.
  • printenv | grep -E '^(DB|SMTP|REDIS)_' | cut -d= -f1 lists the link variables that are present.

Next.js on Wodby

What this service adds to the Node.js service it is based on.

Build and start

The service's Dockerfile copies the build context to /usr/src/app, runs npm run build and starts the container with npm run start. package.json must define both scripts, normally next build and next start.

  • The Dockerfile does not install dependencies. The pipeline does it before the image is built (wodby ci run -- npm ci), and node_modules is copied with the code.
  • npm run build runs while the image is built. Runtime variables of the service, including the link variables and secrets, are not available to it. Pages that need them must be rendered at request time, not prerendered during the build.
  • The application must listen on port 3000, which next start does by default.

Variables the service sets

VariableMeaning
NODE_ENVproduction in every environment type, including dev. The Node.js service's development value for dev is replaced, because the container runs a production build.
WORKSPACE_NODE_COMMANDworkspace-node next-start, the start command of a development workspace.

Do not set NODE_ENV to development for a deployed environment: next start serves the production build.

Linked services

The service adds no link variables. The database, mail and Redis or Valkey variables of the Node.js service apply unchanged and are read by server-side code. They are not exposed to the browser.

In a development workspace

  • The application is started with next dev --hostname "$HOST" --port "$PORT", called directly from node_modules, not through the dev script of package.json. Options in that script do not apply.
  • With Next.js 16 or later --webpack is added: the development server uses Webpack, whose file polling works on the checkout's volume, instead of Turbopack.
  • NODE_ENV is development here. A saved file is picked up by the development server without a restart.
  • /.next/ and /next-env.d.ts are kept out of Git status, in addition to the Node.js service's paths.
  • The image build's npm run build does not run in a workspace.

Overview

Technical profile and packaging

This page shows how Node.js (Next.js) is packaged and versioned as a Wodby service, what it exposes at runtime, and which source artifacts it builds on.

Service type

App service

Versions

26, 24, 22

Ports and protocols

3000/HTTP

Labels

nextjs, node, node

Stacks

Use it inside ready-made stacks or your own

These public stacks already include Node.js (Next.js) as part of their default service model. You can start there and customize the stack, or compose your own stack around the same building block.

CI/CD

Build from source and ship changes without extra glue work

Node.js (Next.js) can build from source as part of a stack. Start from a compatible public boilerplate or connect your repository and keep CI/CD and image storage inside the same Wodby workflow.

Next.js Boilerplate

Start from a working boilerplate instead of wiring the build process from scratch.

wodby/nextjs-boilerplate

Git providers

Connect repositories from supported Git providers when this service should build from your own codebase.

CI providers

Wodby CI is the default path, but external CI providers can fit the same build and release workflow when that suits your team better.

Container registries

Keep built images in Wodby Registry by default or store them in another registry without changing how the service is built.

Runtime wiring

Reuse connectivity, storage, and runtime defaults

This service can expose ports, connect to other services, attach persistent storage, and define runtime defaults that become reusable inside stacks rather than being rebuilt case by case.

Endpoints

3000/HTTP

Technical domains

HTTP endpoints from this service can use technical domains with auto-renewed TLS certificates on Wodby.

Service links

These links define which other services can connect to Node.js (Next.js) when it is used inside a stack.