Monorepos and custom build commands

Falak detects how to install and build your app from its root directory: the repository root, or the subfolder you set. When the defaults are not what you need — a custom script, an unusual package manager flag — override them with two site variables.

Root directory

Set Root directory (Settings → Build & runtime, or root_directory in the API) to the repository subfolder the app lives in, for example apps/api. Empty means the repository root.

• Builds run there, and the release is that folder: deploy steps and hooks run in it.
• Docker builds use it as the build context, and resolve the dockerfile and the compose file from it.
• The path is relative, surrounding slashes are trimmed, and ./.. segments are refused. A root directory that resolves outside the checkout (through a symlink, for example) fails the build.

Several Falak sites can use the same repository with different root directories, one per app. A Compose service split into its own site gets its build context as its root directory.

Override install and build

Variable	Replaces	Runs
FALAK_INSTALL_COMMAND	The detected dependency install (npm ci, composer install, …)	sh -c "<value>" in the root directory on the builder
FALAK_BUILD_COMMAND	The detected build step (npm run build, …)	sh -c "<value>"

Set them in the site’s Variables like any other variable. They apply to native builds and take effect on the next deployment.

Site variables

FALAK_INSTALL_COMMAND=pnpm install --frozen-lockfile
FALAK_BUILD_COMMAND=pnpm run build:prod

Monorepos

For an app that lives in its own folder, set the root directory. When the app needs files outside its folder (shared workspace packages, a root lockfile), build from the repository root instead with these patterns:

Node workspaces (pnpm, npm, yarn, bun)

Build the one app with a workspace filter, and give the root package.json a start script that starts it:

Site variables

FALAK_INSTALL_COMMAND=pnpm install --frozen-lockfile
FALAK_BUILD_COMMAND=pnpm --filter @acme/web... build

package.json (repository root)

{
  "private": true,
  "packageManager": "pnpm@9.12.0",
  "scripts": {
    "start": "pnpm --filter @acme/web start"
  }
}

The web process runs npm run start in the release root, which calls your root script. Make sure the app listens on PORT.

A static app inside a monorepo

Build it, then set the site’s web directory (Settings → Build) to the app’s output, for example apps/docs/dist. Caddy serves the document root current/<web directory>.

A PHP app in a subdirectory

Falak’s PHP detection needs composer.json in the app’s root. For a Laravel app in backend/, set the root directory to backend.

Note

Several Falak sites can point at the same repository, each with its own variables and build commands. Push-to-deploy then deploys all of them on every push to the branch.

Seeing what Falak will do

Every build log starts with the detected plan (provider, versions, steps). Locally, with the falak-builder binary from a Falak release, print the plan for a directory:

falak-builder detect .
falak-builder detect --dockerfile .   # the Dockerfile Falak would generate for docker mode
falak-builder detect --runtime bun .  # hint: php, node, bun, deno or static

Next steps

BuildsDetection rules and build-time variables in detail.

Docker ComposeFor multi-service monorepos.