press.toml Reference

The press.toml file declares how to build and render your Press.js documents. It is consumed by the press render command.

Top-level settings

workspace = "."        # base directory for relative paths (default: press.toml directory)

[playwright]           # default Playwright settings for all entries
# ... (see Playwright options below)

[runtime.env]          # default local runtime environment values
# ... (see Runtime configuration below)

[runtime.secrets]      # default local runtime secret mappings
# ... (see Runtime configuration below)

[pdf.my-report]        # document entry
# ... (see Entry settings below)

workspace

Base directory for all relative paths in this config. Defaults to the directory containing press.toml.

Runtime configuration

Runtime configuration controls the values exposed during press render through pressCloud.env, pressCloud.secrets, and the internal https://p.press.internal/environment.json endpoint.

[runtime.env]
API_URL = "http://localhost:8787"

[runtime.secrets]
API_TOKEN = "PRESS_API_TOKEN"

[pdf.report.runtime.env]
TENANT = "acme"

[pdf.report.runtime.secrets]
WEBHOOK_SECRET = "REPORT_WEBHOOK_SECRET"

Top-level [runtime.env] and [runtime.secrets] are defaults for every entry. Per-entry [pdf.<entry>.runtime.env] and [pdf.<entry>.runtime.secrets] override or add values for that entry.

Environment values are written directly in press.toml. Secret values are not: each [runtime.secrets] key is the secret name exposed to the page, and each value is the source environment variable name the CLI should read.

For the example above:

• pressCloud.env.get("API_URL") returns "http://localhost:8787"
• pressCloud.env.get("TENANT") returns "acme" for the report entry
• pressCloud.secrets.get("API_TOKEN") reads process.env.PRESS_API_TOKEN
• pressCloud.secrets.get("WEBHOOK_SECRET") reads process.env.REPORT_WEBHOOK_SECRET

.dev.vars

Before local rendering, the CLI automatically reads .dev.vars from the selected entry’s workspaceDir, then overlays the current process environment. Process environment variables win over .dev.vars.

.dev.vars

PRESS_API_TOKEN=dev-token
export REPORT_WEBHOOK_SECRET="local webhook secret"

The parser supports blank lines, comments, KEY=value, optional export, and single or double quoted values. It does not expand variables.

If a configured secret source environment variable is missing, press render fails before opening the browser. The error names the missing secret and source variable, but never prints the secret value.

Note

press render --remote does not forward local [runtime.env], [runtime.secrets], or .dev.vars values to Press.js Cloud. Remote renders use the deploy environment and secrets configured in Cloud. Local payload_path is still forwarded as render payload input.

Document entries ([pdf.<name>])

Each entry describes one document to render. Define as many as you need.

[pdf.report]
path = "./dist"                        # required: built artifact directory (relative to workspace)
route = "/"                            # required: app route the SPA serves at
output = "./artifacts/report.pdf"      # required: output PDF path
title = "My Report"                    # optional: PDF title (defaults to entry name)
build = "npm run build"                # optional: build command to run before rendering
workspace = ".."                       # optional: overrides root workspace for this entry
timeout_ms = 30000                     # optional: render timeout in milliseconds
payload_path = "./mock.json"      # optional: path to mock payload file
payload_mime = "application/json" # optional: MIME type for mock payload

[pdf.report.runtime.env]
TENANT = "acme"                   # optional: entry-specific runtime env

[pdf.report.runtime.secrets]
WEBHOOK_SECRET = "REPORT_WEBHOOK_SECRET" # optional: entry-specific secret mapping

Entry fields

Field	Required	Type	Default	Description
path	Yes	string	—	Directory containing built web assets (relative to workspace). Must contain index.html.
route	Yes	string	—	Root route the SPA serves (e.g. "/", "/report"). Leading slash is added if missing.
output	Yes	string	—	Output PDF file path. .pdf extension is appended if missing.
title	No	string	Title-cased entry name	Document title displayed in PDF metadata. Entry names like "my-report" become "My Report".
build	No	string	—	Shell command executed before rendering (e.g. "npm run build", "pnpm build"). Runs from the entry’s workspace directory.
workspace	No	string	root workspace	Override the base workspace directory for this entry only.
timeout_ms	No	integer	—	Maximum time in milliseconds for the full render pipeline. If exceeded, the render fails.
payload_path	No	string	—	Path to a file whose contents are served as the mock payload response. Used for local testing.
payload_mime	No	string	"application/json; charset=utf-8"	MIME type for the mock payload response. Only meaningful when payload_path is set.

Playwright options

Configure how the CLI acquires and runs Chromium. These can be set at the root level (applies to all entries) or per-entry (merged over root settings).

[playwright]
mode = "launch"              # "auto" | "launch" | "connect" | "cdp"
channel = "chrome"           # browser channel name
executable_path = "/usr/bin/chromium"  # path to browser executable
headless = true
args = ["--disable-gpu"]     # additional browser launch args
timeout_ms = 30000           # Playwright operation timeout
slow_mo = 100                # slow motion delay in ms
ws_endpoint = "ws://..."     # WebSocket endpoint (connect mode)
endpoint_url = "http://..."  # CDP endpoint URL (cdp mode)
expose_network = "*"         # network exposure (connect mode)

[playwright.headers]
Authorization = "Bearer ..." # custom HTTP headers

Playwright fields

Field	TOML key	Type	Default	Description
mode	mode	string	"auto"	Browser acquisition mode. "auto": chooses automatically; "launch": launches a new browser; "connect": connects to an existing browser via WebSocket; "cdp": connects via CDP endpoint.
channel	channel	string	—	Browser channel (e.g. "chrome", "msedge").
executable_path	executable_path	string	—	Path to a specific browser executable. If unset, Playwright searches for bundled Chromium, then common system locations.
headless	headless	boolean	true	Run the browser in headless mode. Set to false for debugging.
args	args	string[]	—	Additional command-line arguments passed to the browser (e.g. ["--disable-gpu"]).
timeout_ms	timeout_ms	integer	—	Timeout for Playwright navigation and page operations (in milliseconds).
slow_mo	slow_mo	integer	—	Slow motion delay between Playwright actions (in milliseconds). Useful for debugging renders.
ws_endpoint	ws_endpoint	string	—	WebSocket endpoint URL (required for connect mode).
endpoint_url	endpoint_url	string	—	CDP endpoint URL (required for cdp mode).
expose_network	expose_network	string	—	Network exposure level for connect mode (e.g. "*" for all interfaces).
headers	headers	table	—	Custom HTTP headers sent with WebSocket or CDP connections.

Auto mode resolution: When mode is "auto" (or unset), the behavior is:

• If ws_endpoint is set → "connect"
• If endpoint_url is set → "cdp"
• Otherwise → "launch"

Per-entry Playwright settings

Override Playwright options for a specific entry by nesting a [playwright] table inside the entry:

[pdf.report.playwright]
mode = "connect"
ws_endpoint = "ws://browser-server:9222/devtools/browser/..."

Per-entry settings are deep-merged over the root [playwright] defaults. Headers are merged at the individual header key level.

Multiple entries example

workspace = "."

[playwright]
mode = "launch"
headless = true

[pdf.report]
path = "./apps/report/dist"
route = "/"
output = "./artifacts/report.pdf"
title = "Quarterly Report"
build = "pnpm --filter @my-app/report build"

[pdf.invoice]
path = "./apps/invoice/dist"
route = "/invoice"
output = "./artifacts/invoice.pdf"
title = "Invoice"
build = "pnpm --filter @my-app/invoice build"
timeout_ms = 10000

Render a specific entry by passing its name to the CLI:

press render report
press render invoice

How the CLI uses press.toml

When you run press render [entry], the CLI:

1. Loads and parses press.toml from the current directory (or --config path)
2. Selects the named entry — if omitted and there’s only one entry, it’s auto-selected
3. Runs the build command if specified
4. Routes internal browser requests to files in the artifact directory
5. Routes local runtime payload, environment, secrets, and data-access revocation through https://p.press.internal
6. Spins up Chromium (via Playwright), navigates to the app, runs the pagination pipeline, and exports to PDF
7. Prints a render summary with page count and timing

With press render --remote, steps 1-3 still happen locally. The CLI then hands the resolved artifact path, route, title, output path, timeout, and optional payload_path settings to the installed press-cloud-cli so Press.js Cloud performs the render. Local runtime env/secrets settings are not sent to Cloud.

See also

• press render reference — all render command options
• Page size presets — values for page dimensions