Configuration

Project configuration is .falz/config.yaml. Paths are resolved from the project root unless noted otherwise.

Print the loaded configuration, including computed paths and defaults, with:

falz config

A practical configuration

output: dist
layout: layout.xml
pipes: [md, page]
ignore:
  - drafts/**
  - "*.tmp"

variables:
  site_name: Tiny site
  api_token: $SITE_API_TOKEN

watch:
  debounce_ms: 150
  server:
    serve: false
    hot_reload: false
    host: 0.0.0.0
    port: 8080
    open_browser: true
    port_retries: 50

build:
  force: false
  concurrency: 0
  use_cas: true
  clean: false

index:
  concurrency: 0
  max_concurrent_groups: 4
  kv_buffer_size: 10

A concurrency value of 0 means “use logical CPU count” for build.concurrency and index.concurrency. Keep index.max_concurrent_groups positive.

Project settings

Key	Default when omitted	Meaning
`output`	`dist`	Output directory. Relative paths start at the project root. The global `--output` flag overrides it.
`ignore`	`[]`	Source paths to skip. See ignore patterns.
`debug`	`false`	Project-level diagnostic setting. Current custom bundle output is controlled by each pipe's own `debug` setting.
`force_hash`	`false`	Hash every file instead of reusing hashes when size and modification time are unchanged.
`layout`	`layout.xml`	Layout filename or glob searched in the scheme tree, such as `*.layout.xml`.
`pipes`	`[md]`	Custom pipes to load, plus names included in index KV snapshots. Built-in pipes remain available.
`template_config`	see below	Opening and closing delimiters for layout placeholders and conditional blocks.
`variables`	`{}`	Values exposed to custom pipes as `this.globals`.
`hooks`	empty	Reserved pre/post script lists; current build code does not execute them.

Ignore patterns

Paths use forward slashes and are relative to the project root.

drafts ignores that path and everything below it.
drafts/** does the same with explicit prefix syntax.
*.tmp uses Go-style glob matching and only matches at the corresponding path level.
content/?old and character classes such as [ab] follow Go path.Match rules.

Falz automatically excludes .falz/** and the configured output directory from the source walk. Pipe configuration and pipeline.dbg.js live below .falz/, so they need no user ignore rule.

Variables

Variables may be nested YAML values:

variables:
  site:
    title: My site
    features: [search, feeds]
  token: $API_TOKEN

A string whose first character is $ is replaced by that environment variable. The whole string is replaced; interpolation inside a larger string is not supported. A missing environment variable becomes an empty string.

Custom pipes read these values through this.globals. <Var> values from layouts are separate and available through this.vars.

`template_config`

The accepted keys are:

template_config:
  open_tag: "{{"
  close_tag: "}}"

open_tag sets the opening delimiter and close_tag sets the closing delimiter for layout placeholders and conditional blocks. The defaults are {{ and }}. Output-path placeholders such as {FILENAME} use their fixed single-brace syntax.

`hooks`

The schema accepts:

hooks:
  pre_scripts: []
  post_scripts: []

They are not executed by the current build phase. Use an external task runner or shell script around Falz for now.

`watch`

Key	Default when omitted	Meaning
`watch.debounce_ms`	`150`	Quiet time after file events before processing a batch. Non-positive loaded values are reset to `150`.
`watch.server.serve`	`false`	Start the development HTTP server. Same intent as `watch --serve`.
`watch.server.hot_reload`	`false`	Enable browser notifications. Requires `serve`.
`watch.server.host`	`0.0.0.0`	Listen address. Use `127.0.0.1` for local-only access.
`watch.server.port`	`8080`	Preferred port.
`watch.server.open_browser`	`true`	Open a browser after the server starts.
`watch.server.port_retries`	`50`	Schema value for alternate-port attempts. Current watch code uses its built-in retry count; an explicitly passed `--port` disables retries.

The server serves output, disables browser caching, and tries name.html when a request for extensionless /name does not exist.

Changing watch server settings while falz watch runs requires a restart. Other selected settings, including ignore rules, pipes, variables, and build configuration, are reloaded.

`build`

Key	Default when omitted	Meaning
`build.force`	`false`	Rebuild every entry instead of applying the manifest dirty check. Same intent as `build --force`.
`build.concurrency`	logical CPUs	Maximum parallel transform workers. A non-positive value resolves to logical CPU count.
`build.use_cas`	`true`	Use the content-addressed output cache.
`build.clean`	`false`	Remove outputs whose manifest entries no longer exist in the current scan.

The build cache location is computed under the operating system's user cache directory and shown by falz config as read-only cas_path.

`index`

Key	Default when omitted	Meaning
`index.concurrency`	logical CPUs	Maximum concurrent `index()` calls. A non-positive value resolves to logical CPU count.
`index.max_concurrent_groups`	`4`	Maximum pipe groups active at once. Keep this at least `1`; `0` prevents groups from starting.
`index.kv_buffer_size`	`10`	Successful entry results buffered before KV state is flushed.

Blob and KV cache paths are computed under the user cache directory and shown by falz config.

Computed read-only entries

falz config prints these as comments for diagnosis; they are not YAML settings:

Display name	Meaning
`source_path`	Absolute project/source root.
`scheme_path`	Absolute `.falz/schemes` path.
`pipes_path`	Absolute `.falz/pipes` path.
`cas_path`	Build output cache path.
`blob_cas_path`	Per-entry index blob cache path.
`kv_cas_path`	Cross-entry index KV cache path.

Cache paths are derived from the cleaned absolute source path, so moving the project gives it a different cache root.

Minimal generated configuration

falz init writes only the choices made during initialization:

output: dist
pipes:
  - md

Omitted settings receive the defaults documented on this page. This keeps a new project ready to build without copying the full schema into source control. Add an entry when the project needs to override it, and use falz config to inspect the fully resolved result.

Pipe configuration

Each custom pipe has its own .falz/pipes/<name>/config.yaml for entry point, timeout, debug bundle, and HTTP permissions. It is documented in Pipe reference: pipe configuration.