Service type
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.
Why teams use this service
Technical profile
Review versions, ports, source, and packaging.
Stacks that use it
See where this service fits in ready-made stacks.
Source builds and CI/CD
Start from a compatible boilerplate, use Wodby CI, and publish images cleanly.
Runtime wiring and defaults
See ports, links, storage, configs, and runtime behavior.
On Wodby
How Node.js (Next.js) runs on Wodby
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_PORTto that number; it does not setPORT. ReadNODE_PORT, or default to 3000. NODE_ENVisdevelopmentin environments of typedevandproductionin 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.
| Link | Variables |
|---|---|
| Database (MariaDB, MySQL or PostgreSQL) | DB_HOST, DB_PORT, DB_NAME (also DB_DATABASE), DB_USERNAME, DB_PASSWORD, DB_DRIVER (also DB_CONNECTION) |
SMTP_HOST, SMTP_PORT | |
| Redis or Valkey | REDIS_HOST, REDIS_PORT, REDIS_PASSWORD |
| OpenTelemetry Collector | OTEL_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_HOSTSis a JSON array of the environment's hosts, not a comma-separated string.WODBY_PRIMARY_HOSTandWODBY_PRIMARY_URLare the canonical ones for links generated outside a request.WODBY_APP_SERVICE_NAMEis this service's host name inside the environment. Other services reach the application at that name on port 3000.WODBY_ENV_TYPEtells a development environment from a production-like one.
In a development workspace
- The checkout is mounted at
/usr/src/appand served as it is on disk. - Workspace setup installs dependencies with
workspace-node prepare. The package manager is taken frompackageManagerinpackage.json, otherwise from the lockfile:pnpm-lock.yamlmeans pnpm,yarn.lockmeans 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
devscript ofpackage.jsonwhen there is one, otherwise withstart.WORKSPACE_NODE_COMMANDon the service replaces that command. NODE_ENVis alwaysdevelopmenthere, whatever the environment type.PORTis set, toNODE_PORTunless given, andHOSTto0.0.0.0.- A saved file is picked up without a restart or a deployment. A
devscript is expected to watch the files itself. Astartscript 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,buildandcoverageare not watched. A command set withWORKSPACE_NODE_COMMANDis run as it is, without that watcher;WORKSPACE_NODE_WATCH=0turns the watcher off. For scripts with their own watcher,CHOKIDAR_USEPOLLING,CHOKIDAR_INTERVALandWATCHPACK_POLLINGare set, because a checkout on network storage needs polling.WORKSPACE_POLL_INTERVALchanges the interval,WORKSPACE_POLLING=0turns 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= -f1lists 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), andnode_modulesis copied with the code. npm run buildruns 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 startdoes by default.
Variables the service sets
| Variable | Meaning |
|---|---|
NODE_ENV | production 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_COMMAND | workspace-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 fromnode_modules, not through thedevscript ofpackage.json. Options in that script do not apply. - With Next.js 16 or later
--webpackis added: the development server uses Webpack, whose file polling works on the checkout's volume, instead of Turbopack. NODE_ENVisdevelopmenthere. A saved file is picked up by the development server without a restart./.next/and/next-env.d.tsare kept out of Git status, in addition to the Node.js service's paths.- The image build's
npm run builddoes not run in a workspace.
Overview
Technical profile and packaging
Versions
Built on top
Source repository
Public Helm chart
Ports and protocols
Labels
Stacks
Use it inside ready-made stacks or your own
CI/CD
Build from source and ship changes without extra glue work
Next.js Boilerplate
Start from a working boilerplate instead of wiring the build process from scratch.
wodby/nextjs-boilerplateGit 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.
Keep secrets and variables outside the codebase
Attach provider credentials and environment variables at the platform level so the build and runtime do not depend on hardcoded secrets.
Runtime wiring
Reuse connectivity, storage, and runtime defaults
Endpoints
Technical domains
Service links
These links define which other services can connect to Node.js (Next.js) when it is used inside a stack.
db
Eligible linked services
sendmail
Eligible linked services
redis
Eligible linked services
otel
Eligible linked services