Configuration can be declared in the root Composer package and in individual installed packages.
The preferred key is nested under extra.sympress.asset-compiler:
{
"extra": {
"sympress": {
"asset-compiler": {}
}
}
}The flat key extra.sympress.asset-compiler is also supported. The legacy key extra.composer-asset-compiler is accepted for migration compatibility.
The root policy schema describes the trust and installation settings. Remaining existing configuration keys remain supported.
| Key | Type | Default | Description |
|---|---|---|---|
auto-run |
boolean | false |
Run the compiler after Composer install and update events. Auto-run uses a late event priority and prints the same compilation summary as the manual command. |
auto-discover |
boolean | true |
Discover packages with build scripts automatically. |
stop-on-failure |
boolean | true |
Stop the run after the first failing package. |
max-processes |
integer | 4 |
Number of package builds to run in parallel. Values are clamped to 1..8. |
execution-strategy |
string | staged |
Process scheduling strategy. Supports staged and grouped. |
process-poll |
integer | 100000 |
Poll interval in microseconds for parallel process execution. |
isolated-cache |
boolean | false |
Use package-specific npm/yarn/pnpm cache directories inside a private per-user directory (sympress-asset-compiler-<uid>, mode 0700) below the system temp directory. |
wipe-node-modules |
boolean | false |
Remove node_modules after a successful package build when the compiler created it during the run. |
clear-package-manager-cache |
boolean | false |
Remove isolated npm/yarn/pnpm caches after a successful package build. Only applies when the package uses isolated-cache. |
timeout-increment |
integer | 0 |
Additional timeout seconds added progressively across the package plan. |
package-manager |
string | auto-detected | Project-wide package-manager preference. Supports npm, yarn, and pnpm. Package-level config, package.json packageManager, and unambiguous lock files still win per package. npm remains the final fallback. Unsupported values fail early. |
allow-lifecycle-scripts |
boolean | false |
Root-only authorization for dependency install lifecycle scripts. Package metadata cannot enable it. |
allow-package-config-files |
boolean | false |
Allow package-local asset-compiler.json and assets-compiler.json files to override Composer extra for that package. Keep disabled for stricter supply-chain control. |
require-precompiled-checksum |
boolean | true in --no-dev, otherwise false |
Require SHA-256 checksums for remote precompiled archives. |
package-types |
string list | WordPress package types | Local path package types considered during auto-discovery. |
default-env |
object | {} |
Environment variables passed to asset commands. Use false to unset a variable. |
defaults |
object | {} |
Default package build configuration. |
packages |
object | {} |
Explicit package selections, overrides, or disabled packages. |
| Key | Type | Default | Description |
|---|---|---|---|
script |
string or string list | build when package.json has a build script |
Script or scripts to run. |
dependencies |
string | install when scripts are present |
install, update, or none. |
package-manager |
string | auto-detected | npm, yarn, or pnpm. |
default-env |
object | {} |
Package-level command environment merged over root environment. |
src-paths |
string list | auto-discovered hash inputs | Optional files or directories that affect the build hash. |
source-paths |
string list | alias for src-paths |
Compatibility alias. |
timeout |
integer | 900 |
Process timeout in seconds. Minimum value is 60. |
isolated-cache |
boolean | root value | Override isolated package-manager cache behavior for one package. |
require-precompiled-checksum |
boolean | root value | Override remote precompiled checksum enforcement for one package. |
precompiled |
object or object list | [] |
Restore ZIP assets from archives or GitHub before falling back to local builds. |
pre-compiled |
object or object list | alias for precompiled |
Migration alias. |
When package config files are enabled, they must contain valid JSON. Invalid local config files fail with a clear error instead of being ignored silently.
The default staged strategy installs or updates dependencies for all selected packages first, then runs build scripts through the bounded process pool. This keeps package-manager installs predictable and preserves the historical behavior.
The grouped strategy runs each package as a sequential pipeline while different packages may run in parallel. For large CI jobs, pair it with wipe-node-modules, isolated-cache, and clear-package-manager-cache to lower peak disk usage:
{
"execution-strategy": "grouped",
"max-processes": 2,
"isolated-cache": true,
"wipe-node-modules": true,
"clear-package-manager-cache": true
}When the root project sets "allow-package-config-files": true, packages can store the same package build object in a root-level JSON file:
asset-compiler.jsonassets-compiler.json
The file wins over Composer extra for that package only when package config files are allowed. Short forms are supported:
"build"Object form:
{
"script": "build",
"dependencies": "install",
"package-manager": "yarn"
}The root packages map can require, disable, or override specific packages.
{
"extra": {
"sympress": {
"asset-compiler": {
"packages": {
"acme/theme": true,
"acme/experimental-*": false,
"acme/admin": {
"script": ["build", "build:admin"],
"dependencies": "install"
},
"acme/legacy": "$force-defaults"
}
}
}
}
}Supported values:
| Value | Meaning |
|---|---|
false or "disabled" |
Never build matching packages. |
true or "package-or-defaults" |
Explicitly include matching packages and prefer package config when present. |
"$force-defaults" or "$defaults" |
Explicitly include matching packages and apply root defaults. |
| string | Use the string as the script name. |
| string list | Use the list as script names. |
| object | Merge the object as a package override. |
Concrete package names in packages are treated as required when stop-on-failure is enabled. If a required package is missing from Composer's local repository, compilation fails early.
Any config object or config property can contain a $mode object. The selected mode is resolved in this order:
- The explicit
--modeoption. $default-no-devwhen the command is run with--no-dev.$default.
The legacy env key is treated like $mode for compatibility.
{
"extra": {
"sympress": {
"asset-compiler": {
"defaults": {
"script": {
"$mode": {
"$default": "build",
"production": "build:production"
}
},
"dependencies": {
"$mode": {
"$default": "install",
"$default-no-dev": "none"
}
}
}
}
}
}
}The compiler reads these environment variables before root configuration is finalized:
| Variable | Meaning |
|---|---|
COMPOSER_ASSETS_COMPILER or COMPOSER_ASSET_COMPILER |
Default mode when no --mode option is passed. |
COMPOSER_ASSET_COMPILER_PRECOMPILING |
Disable auto-discovery for precompilation-oriented runs. |
COMPOSER_ASSET_COMPILER_AUTO_DISCOVER |
Override auto-discover. |
COMPOSER_ASSET_COMPILER_STOP_ON_FAILURE |
Override stop-on-failure. |
COMPOSER_ASSET_COMPILER_MAX_PROCESSES |
Override max-processes. |
COMPOSER_ASSET_COMPILER_EXECUTION_STRATEGY |
Override execution-strategy. |
COMPOSER_ASSET_COMPILER_PROCESSES_POLL |
Override process-poll. |
COMPOSER_ASSET_COMPILER_ISOLATED_CACHE |
Override isolated-cache. |
COMPOSER_ASSET_COMPILER_WIPE_NODE_MODULES |
Override wipe-node-modules. |
COMPOSER_ASSET_COMPILER_CLEAR_PACKAGE_MANAGER_CACHE |
Override clear-package-manager-cache. |
COMPOSER_ASSET_COMPILER_TIMEOUT_INCR |
Override timeout-increment. |
COMPOSER_ASSET_COMPILER_PACKAGE_MANAGER |
Override the root package-manager preference. |
COMPOSER_ASSET_COMPILER_ALLOW_PACKAGE_CONFIG_FILES |
Override allow-package-config-files. |
COMPOSER_ASSET_COMPILER_REQUIRE_PRECOMPILED_CHECKSUM |
Override require-precompiled-checksum. |
Script strings may reference ${NAME} placeholders. Values resolve only from approved merged default-env. Unresolved and protected placeholders fail without exposing their values. Inherited environment secrets cannot enter command arguments or verbose logs.
Precompiled assets are attempted before local dependency installation and build scripts. A successful restore writes the package lock hash. If no matching precompiled config exists or the restore fails, the compiler falls back to the normal local build.
{
"precompiled": [
{
"adapter": "archive",
"source": "https://example.test/${package}-${version}.zip",
"target": "assets",
"stability": "stable",
"checksum": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
},
{
"adapter": "github-artifact",
"source": "assets-${ref}",
"target": "assets",
"config": {
"repository": "vendor/repository"
}
}
]
}Supported adapters:
| Adapter | Source |
|---|---|
archive or zip |
Local file path or HTTPS ZIP URL. |
github-release or gh-release-zip |
GitHub release asset matched by source; requires config.repository, optional config.tag. |
github-artifact or gh-action-artifact |
GitHub Actions artifact matched by source; requires config.repository. |
Supported placeholders in source, target, checksum, and GitHub tag are ${name}, ${vendor}, ${package}, ${version}, ${ref}, ${reference}, and ${stability}.
GitHub adapters use config.token, GITHUB_TOKEN, or GH_TOKEN when available. Tokens are scoped to trusted GitHub API/download hosts and are not forwarded to arbitrary redirect targets. ZIP targets are relative package paths, are validated against traversal and symlink escapes, and are cleaned by default; set "config": {"clean-target": false} to merge into an existing target.
Optional SHA-256 verification can be configured through checksum, sha256, config.checksum, or config.sha256. Values may be raw 64-character hashes or sha256:<hash>.
Remote precompiled archives require a SHA-256 checksum by default when the compiler runs in Composer no-dev mode.
Precompiled downloads and extraction are intentionally bounded:
- Downloads use HTTPS only and reject non-HTTPS redirects.
- Generic archive redirects must stay on the same host.
- GitHub archive redirects are restricted to known GitHub/GitHub-backed download hosts.
- Downloads are limited to 100 MiB by default.
- ZIP extraction is limited to 20,000 entries, 100 MiB per entry, and 512 MiB total uncompressed size.
- ZIP entries with absolute paths or
..path segments are rejected. - ZIP archives are extracted into a package-local staging directory before replacing or merging into the target.
Auto-discovery includes packages that have a readable package.json with a scripts.build entry and match the configured discovery policy.
The root package and eligible Composer path packages retain default discovery.
All downloaded vendor packages require an explicit enabled root packages
selection before their package manifests/configuration are parsed. Package-owned
metadata, sympress/assets requirements, custom types and kernel bundle metadata
cannot authorize vendor execution. A root wildcard is explicit trust in all
matching packages. Disabled matches win over enabled wildcards. CLI --packages
only narrows discovered candidates and never grants trust.
--mode production and --no-dev require the selected manager's real lockfile
and frozen installation; dependency update mode fails. The compiler freshness
lock is independent of npm/pnpm/Yarn locks. npm and pnpm use --ignore-scripts
by default; Yarn 1 uses --ignore-scripts, while Yarn 2+ uses
YARN_ENABLE_SCRIPTS=false with --immutable and a build-phase skip flag
(--skip-builds for Yarn 2, --mode=skip-build for Yarn 3+). Environment control
alone does not stop workspace hooks. See the Yarn install documentation. Yarn generation must be verified;
unsupported modern isolated-cache flags fail without retrying legacy commands.
Explicit build scripts remain authorized and can run their pre/postbuild hooks.
Sequential/pool builds and version probes inherit only ordinary execution
variables (PATH, HOME, temp paths, locale, terminal and CI). Install authentication,
SSH agents, registry/cloud/database secrets and injection controls are removed.
Protected names cannot be re-enabled by package or root metadata. Ordinary
configured build variables remain available and explicit false unsets work.
This filters environment inheritance; it does not sandbox filesystem/network
access. Trusted build code can still read files accessible through HOME.
The build hash includes:
- Composer package name, explicit package-manager name, and root package-manager preference.
- The resolved package manager, its version, the Node.js version, and why the manager was selected.
- Dependency mode, production/lifecycle policy and environment policy version.
- Configured scripts and environment.
- Precompiled asset configuration.
composer.json,package.json, common lock files, and frontend config files.- Common frontend source directories such as
resources,src,source,frontend,client,assets-src,blocks,components,scripts,styles,views, andtemplates. - Configured
src-pathswhen a package needs to override the automatic inputs.
Fresh packages are skipped unless --ignore-lock matches the package name.
The packages selection also applies to the root Composer package. Set its name to false when the root npm build orchestrates Composer installation or compile-assets, rather than compiling its own assets. For example, "packages": {"sympress/demo": false, "sympress/demo-plugin": true} compiles only the feature plugin.
Every asset dependency/build child inherits the reserved SYMPRESS_ASSET_COMPILER_ACTIVE=1 marker. Nested Composer automatic compilation is skipped; an explicit nested compile-assets invocation fails before discovery, installation or lock writes. Package environment configuration cannot replace or remove the marker. Deployment wrappers that change Composer dependencies must reject a nonempty marker before any command runs. This prevents accidental recursion by trusted scripts; build scripts remain trusted executable code.