Pipe reference

For a first custom pipe, follow Pipes. This page collects the runtime and configuration details for later lookup.

Built-in pipes

`pipe` value	Behavior
omitted	Pass input through unchanged.
`md`	Convert Markdown to an HTML fragment.
`tpl`	Render a Plush template with entry variables.

Built-ins are always registered. Custom pipes must appear in project pipes.

JavaScript and TypeScript support

The entry point must be TypeScript and defaults to index.ts. Falz bundles it with esbuild for ES2020, so it can import:

local .ts, .tsx, and JavaScript files;
helpers under .falz/pipes/shared/;
compatible npm packages;
Falz's built-in modules.

The generated declarations under .falz/types/ provide editor types. Falz bundles TypeScript but does not run tsc as a separate type-checking step; run it yourself when you want stricter CI checks:

cd .falz/pipes/page
npx tsc --noEmit

Runtime support is intentionally smaller than Node.js. There is no general Node fs, fetch, process, or native-addon environment. Use Falz's modules documented in the JavaScript API.

TypeScript configuration

The scaffold commands create three TypeScript configurations.

.falz/pipes/tsconfig.json contains the common compiler settings:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "noEmit": true,
    "skipLibCheck": true,
    "lib": ["ES2020"]
  }
}

.falz/pipes/shared/tsconfig.json configures shared helpers and Falz declarations:

{
  "extends": "../tsconfig.json",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@shared/*": ["shared/*"]
    }
  },
  "include": [
    "**/*.ts",
    "**/*.tsx",
    "../../types/*.d.ts"
  ]
}

Each pipe has .falz/pipes/<name>/tsconfig.json:

{
  "extends": "../tsconfig.json",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@shared/*": ["../shared/*"]
    },
    "typeRoots": [
      "node_modules",
      "../shared/node_modules"
    ]
  },
  "include": [
    "**/*.ts",
    "**/*.tsx",
    "../shared/**/*.ts",
    "../shared/**/*.tsx",
    "../../types/*.d.ts"
  ]
}

Install npm packages

Falz does not run npm for you. Install a package inside the pipe that uses it:

cd .falz/pipes/page
npm install slugify

Then import it normally:

import slugify from "slugify"

export function transform(this: tCtx, input: Buffer): TransformResult {
  const alias = slugify(this.file.stem, { lower: true, strict: true })
  return { content: input, alias }
}

The package and its transitive dependencies are bundled. Pure JavaScript packages that target ES2020 are the safest choice. Packages that require Node built-ins, dynamic filesystem access, native .node addons, or an asynchronous host API generally will not work in the pipe runtime.

Put code in .falz/pipes/shared/ and import it through the generated alias:

import { escapeHTML } from "@shared/html"

To share npm dependencies, initialize and install them in the shared directory:

cd .falz/pipes/shared
npm init -y
npm install some-package

Falz resolves dependencies from the current pipe's node_modules and then the shared node_modules. Imports are sandboxed to .falz/pipes/; they cannot bundle arbitrary files from the rest of the machine.

Pipe configuration

.falz/pipes/page/config.yaml:

name: page
entryPoint: index.ts
debug: false
transformTimeoutMs: 3000

http:
  timeout: 30s
  maxBodyBytes: 33554432
  maxConnsPerHost: 8
  maxRedirects: 10
  maxBytesPerTransform: 0
  allowedHosts: []

Setting	Meaning
`name`	Pipe name used by layouts and project configuration.
`entryPoint`	TypeScript entry file, relative to the pipe directory. Default `index.ts`.
`debug`	Write the generated bundle to `pipeline.dbg.js`. It is for inspection, not source control.
`transformTimeoutMs`	Wall-clock limit for each `transform()` or `index()` call. `0` or negative disables this limit. Default `3000`.
`http.timeout`	Per-request timeout as a duration (`30s`) or milliseconds. `0` or negative means no client deadline.
`http.maxBodyBytes`	Maximum bytes in one response. Default 32 MiB; `0` or negative is unlimited.
`http.maxConnsPerHost`	Shared connection limit per host. Default `8`; `0` or negative is unlimited.
`http.maxRedirects`	Redirect limit. Default `10`; `0` or negative is unlimited. Redirect targets must also be allowlisted.
`http.maxBytesPerTransform`	Total response bytes across HTTP calls in one pipe call. `0` is unlimited.
`http.allowedHosts`	Exact hosts, `host:port`, or wildcards such as `*.example.com`. Empty disables outbound HTTP.

A build warns about HTTP-enabled pipes. Review their code and allowlist, then use global --trust-pipes only if you want to suppress the warning.