Build Configuration

The build section in pilum.yaml defines how your application is compiled.

Basic Structure

build:
  language: go
  version: "1.23"
  cmd: "go build -o ./dist/app ."
  env_vars:
    CGO_ENABLED: "0"

Fields

Field	Type	Description
language	string	Programming language (go, node, python, rust) — informational
version	string	Language version
cmd	string	Build command to execute
env_vars	map	Environment variables for build
flags	map	Build flags (language-specific, e.g., ldflags for Go)
output	string	Output path for built artifact
output_dir	string	Directory containing build output (used by Cloudflare Pages)

Note

The language field is informational — it’s used by pilum init to generate templates but does not affect how the cmd field is executed. The cmd field is what actually runs.

Language Examples

Go

build:
  language: go
  version: "1.23"
  cmd: "go build -o ./dist/app ."
  env_vars:
    CGO_ENABLED: "0"
    GOOS: linux
    GOARCH: amd64
  flags:
    ldflags:
      - "-s"
      - "-w"

Version Injection

Inject the release tag into your binary at build time:

build:
  language: go
  cmd: "go build -o ./dist/app ."
  flags:
    ldflags:
      - "-X main.version=${TAG}"

Node.js

build:
  language: node
  version: "20"
  cmd: "npm run build"
  env_vars:
    NODE_ENV: production

Package Managers

When using the npm provider, the npm.package_manager field controls which install command runs before your build:

Value	Install Command
npm (default)	npm ci
pnpm	pnpm install --frozen-lockfile
yarn	yarn install --frozen-lockfile
bun	bun install --frozen-lockfile

build:
  language: node
  cmd: "pnpm run build"

npm:
  package_manager: pnpm

Monorepo Builds

For pnpm workspaces, use the --filter flag with the ... suffix to build a package and all its workspace dependencies in topological order:

build:
  language: node
  cmd: "pnpm --filter @scope/package... build"

npm:
  package_manager: pnpm

The ... suffix is important — without it, workspace dependencies won’t be built first and the build may fail.

Yarn and Bun

# Yarn
build:
  language: node
  cmd: "yarn build"
npm:
  package_manager: yarn

# Bun
build:
  language: node
  cmd: "bun run build"
npm:
  package_manager: bun

Python

build:
  language: python
  version: "3.12"
  cmd: "pip install -r requirements.txt"
  env_vars:
    PYTHONDONTWRITEBYTECODE: "1"
    PYTHONUNBUFFERED: "1"

Rust

build:
  language: rust
  version: "1.75"
  cmd: "cargo build --release"
  flags:
    target:
      - "x86_64-unknown-linux-musl"
  env_vars:
    CARGO_NET_GIT_FETCH_WITH_CLI: "true"

Custom Build Commands

Use any build command:

build:
  language: go
  version: "1.23"
  cmd: "make build"

Or a shell script:

build:
  language: go
  version: "1.23"
  cmd: "./scripts/build.sh"

Build Flags

The flags field passes language-specific flags to the build. For Go, ldflags are appended to the go build command:

build:
  language: go
  cmd: "go build -o ./dist/app ."
  flags:
    ldflags:
      - "-s"                    # Strip symbol table
      - "-w"                    # Strip DWARF debug info
      - "-extldflags '-static'" # Static linking

Environment Variables

Build environment variables are set for the duration of the build command:

build:
  env_vars:
    CGO_ENABLED: "0"
    GOOS: linux
    GOARCH: amd64
    NODE_ENV: production

These are merged with the system environment. Service-specific env vars take precedence over system values.

CLI Help

For a quick reference of build examples by language, run:

pilum build --help

Next Steps

• Service Configuration — Full pilum.yaml reference
• How Recipes Work — Understand build steps
• npm Provider — npm/pnpm/yarn/bun publishing
• Cloudflare Pages — Static site deployment