Build settings

Build-related settings live in the service's Settings under Source, Build and Deploy. They apply per environment.

Root directory

The folder of the repository the service is built from, for example apps/web. Values like /apps/web, apps/web/ and ./apps/web are all treated the same. Leave it empty for the repository root.

The root directory is a working directory, not a jail for generated builds: detection, install, build and the start command run inside it, but the whole repository is the build context, so a build script can read ../shared or ../design/images. For a repository Dockerfile or Nixpacks, the build context is the root directory itself.

If the folder does not exist in the repository, the build fails with the root directory apps/web/ does not exist in the repository.

Builder

• Automatic (default): Dockerfile, else framework detection, else Nixpacks. See How builds work.
• Nixpacks: skip framework detection and use Nixpacks (a Dockerfile still wins).
• Dockerfile: require a Dockerfile; fail if there is none.

Custom build command

Replaces the detected build command (normally your build script), for example npm run build:prod. It runs in the root directory after the dependencies are installed. For a plain HTML site without a package.json there is nothing to build, and the command is ignored.

Start command

Replaces how the service starts. Leave it empty in most cases: the builder already knows how to run each framework, and a repository Dockerfile has its own CMD.

A custom start command is ignored (with a note in the build log) when:

• the service is a static site served by nginx: there is no Node.js process to start;
• it only runs a preview or development server, such as nuxt preview, nuxi dev, vite, vite preview, astro preview, next dev, ng serve, webpack serve, npm run dev, npm run preview, or a script that resolves to one of these. The detected production server is used instead.

A --prefix <root dir> or cd <root dir> && that points at the root directory itself is dropped, because the command already runs there.

A genuine server command, such as node server.js or pm2-runtime ecosystem.config.cjs, is used as is.

Port

The port your app listens on; also the PORT variable given to the app. Web services default to 8080.

Watch paths

Glob patterns, relative to the repository root, that decide whether a push redeploys the service, for example apps/web/**, packages/ui/**, package.json. Empty means every push redeploys. Useful in monorepos with several services.

Where to see the result

Every deployment stores the build plan it used (framework, package manager, Node.js version, install, build and run commands, and whether the start command was ignored). It is printed at the top of the build log.