Skip to main content
Parse one JSON document per command instead of scraping log lines. Under --output json, every terminating command answers with exactly one schema-1 envelope on stdout. Long-running commands stream the same shape as lifecycle frames. From the release after 4.2.0, every JSON run ends with exactly one terminal frame. extension --output json with no command answers one usage frame with E_ARGS and exits 1. A run stopped by SIGINT or SIGTERM before its command answered ends with one stopped frame that carries E_INTERRUPTED and value.signal, and exits 130 or 143.

Envelope shape

The error object:

Success and failure examples

Compile diagnostics

A failed build frame and the dev stream’s compile-failed frame carry error.details, one entry per compiler diagnostic, errors first. Each entry has this shape: The list is capped at 20 entries. When the cap cuts it, the frame sets truncated: true. The error codes that can appear in details are the diagnostic rows of the error code table: E_MODULE_NOT_FOUND, E_CONTENT_SCRIPT_SYNTAX, E_CSS_PARSE, E_ENTRY_NOT_FOUND, E_ASSET_MISSING, E_SCRIPT_DEP_MISSING, E_RESERVED_FOLDER, E_CSS_PREPROCESSOR_MISSING, E_CSS_DEAD_REF, E_LOCALES_LAYOUT, E_WAR_INVALID, and E_PERF_BUDGET. Up to 4.2.0, E_BACKGROUND_REQUIRED could appear there too. A warning entry carries a code from the warning code table. This is golden.build.compile.json with its two messages shortened to their first line:
From the release after 4.2.0, a config file that fails to load (E_CONFIG_LOAD) and an unusable package.json (E_PACKAGE_JSON_INVALID) give the same frame on build, dev, start, and preview. error holds code and message only, with no name, and the top-level hint reads Fix the error above and run <command> again. On preview, the status is failed. A successful build keeps its warnings in the top-level warnings array. Each string there opens with W_CODE: when a code resolves, for example W_CSS_DEAD_REF: ..., the same convention logs and uninstall already use. Releases up to 4.1.41 opened these strings with the E_* name. From the release after 4.1.41, a failed build’s frame carries them too: each coded warning the build had, once, including those from a browser that built before the failure. The array is [] when there is none.

Where human copy goes

The EXTENSION_OUTPUT environment variable is the machine-mode switch. When it is json or ndjson, frames own stdout and human copy moves aside:
  • Informational lines and warnings go quiet, or move to stderr where a stream needs them.
  • Error copy is never suppressed. It writes to stderr, so a launch failure stays visible while stdout stays parseable.
  • From the release after 4.1.41, a refusal while build or dev is still finding the project prints nothing on stderr.
  • For build, that also covers finding the browser. The frame on stdout is then the whole answer.
  • Every later failure, such as a config file that fails to load, also prints its human lines on stderr.
Pipe stdout to your parser and keep stderr for humans. The two never mix.

Published contract artifacts

The extension-develop package ships the contract as importable files under the ./contract/* export: Validate your consumer against the schema, and pin your tests to the golden fixtures. Codes may be added, never renamed or removed.

Next steps