Skip to content

config.md

Latest commit

 

History

History
341 lines (272 loc) · 12.7 KB

config.md

File metadata and controls

341 lines (272 loc) · 12.7 KB
Raw

Configuration

Foxy reads project options from config.foxy in the root composer.json:

{
  "config": {
    "foxy": {
      "manager": "npm"
    }
  }
}

Configuration sources and priority

Values are resolved in this order, from highest to lowest priority:

  1. Environment variables beginning with FOXY__.
  2. The project composer.json file.
  3. <COMPOSER_HOME>/config.json.
  4. <COMPOSER_HOME>/composer.json.
  5. Foxy defaults.

Global values must be placed under config.foxy in one of the two Composer home files. Composer does not accept arbitrary nested options through composer global config, but composer global config --editor can be used to edit the global file directly.

Environment variables

Convert an option name to uppercase, replace hyphens with underscores, and prefix it with FOXY__. For example, run-asset-manager becomes FOXY__RUN_ASSET_MANAGER.

Foxy accepts strings, integers, case-insensitive boolean values (true, false, yes, no, y, n, 1, and 0), and JSON arrays or objects.

FOXY__ENABLED=false composer install
FOXY__MANAGER_TIMEOUT=420 composer install
FOXY__ENABLE_PACKAGES='{"foo/*":true}' composer install

Use shell-appropriate quoting when passing JSON. A manager-specific map is supported in Composer configuration, but a manager-prefixed environment variable should contain the scalar value for the active manager.

Options

Option Type Default Description
enabled boolean true Enables Foxy processing.
manager string or null null Selects bun, npm, pnpm, or yarn; null enables automatic selection.
manager-version string or map Empty Adds a constraint within the built-in supported manager range.
manager-bin string or map Manager executable Overrides the manager executable.
manager-options string or map Empty Appends options to both install and update commands.
manager-install-options string or map Empty Appends options only to install commands.
manager-update-options string or map Empty Appends options only to update commands.
manager-timeout integer or map No practical limit Sets the manager process timeout in seconds.
run-asset-manager boolean true Controls automatic manager probing and install or update execution.
fallback-asset boolean true Restores package.json after asset processing fails.
fallback-composer boolean true Restores Composer lock and vendor state after asset solving fails.
composer-asset-dir string or null <vendor-dir>/php-forge/composer-asset/ Sets the mock package directory.
enable-packages array or object [] Includes or excludes Composer packages by pattern.
root-package-json-dir string or null Project or package root Sets the directory containing package.json.

Disabling Foxy

Set enabled to false to skip manager discovery, fallback snapshots, package merging, and manager execution:

{
  "config": {
    "foxy": {
      "enabled": false
    }
  }
}

Manager selection

Set the manager explicitly when local development and CI must always use the same tool:

{
  "config": {
    "foxy": {
      "manager": "pnpm"
    }
  }
}

When manager is null, Foxy looks for one recognized native lockfile. Multiple recognized lockfiles require explicit selection. Without a lockfile, available executables are considered in this order: npm, pnpm, Yarn, and Bun. Commit the native lockfile generated by the selected manager. Foxy reports an error when an explicitly configured manager is unknown, or when execution is enabled and its executable is unavailable.

When run-asset-manager is false, automatic selection does not probe executables. Foxy uses the manager identified by a single recognized lockfile, or npm as the manifest adapter when no lockfile exists. Multiple lockfiles still require an explicit manager value.

Manager version constraints

When manager execution is enabled, Foxy validates the selected manager against its built-in supported constraint:

Manager Built-in constraint
Bun ^1.4.0
npm >=10.9.8
pnpm ^11.23.0
Yarn ^4.18.0

The manager-version option adds another Composer constraint that is evaluated together with the built-in constraint. It can narrow the accepted versions for a project, but it cannot replace or widen Foxy's supported range. Foxy treats the reported value as one concrete release and validates it from root-package-json-dir before every manager command. During automatic Composer processing, run-asset-manager=false prevents probing, execution, and validation of the manager binary. An explicit composer foxy:audit remains an exception because it is a direct user request.

Narrow the npm constraint for one project:

{
  "config": {
    "foxy": {
      "manager": "npm",
      "manager-version": "~10.9.8"
    }
  }
}

Manager-prefixed options may also use a map when a shared configuration supports several managers:

{
  "config": {
    "foxy": {
      "manager-version": {
        "npm": "~10.9.8",
        "pnpm": "~11.23.0"
      }
    }
  }
}

For example, configuring npm with <10.9.8 does not enable an older release because the built-in >=10.9.8 constraint remains in force. Remove manager-version to accept the complete built-in range for the selected manager.

Manager executable and options

Use manager-bin for an explicit executable path:

{
  "config": {
    "foxy": {
      "manager": "npm",
      "manager-bin": "/opt/node/bin/npm"
    }
  }
}

Use the three manager option settings only when native manager configuration files cannot express the requirement:

{
  "config": {
    "foxy": {
      "manager": "npm",
      "manager-options": "--no-audit",
      "manager-install-options": "--ignore-scripts",
      "manager-update-options": "--save"
    }
  }
}

These values are appended to an external command. Treat project, global, and environment configuration as trusted input. Prefer native files such as .npmrc, .yarnrc.yml, pnpm-workspace.yaml, or bunfig.toml where appropriate. They apply to install and update operations only. foxy:audit owns its machine-output, advisory-filter, and dependency-scope flags and does not inherit these options. It does honor manager-bin, manager-version, manager-timeout, and root-package-json-dir.

Where the native manager supports an explicit override, Foxy neutralizes inherited settings that could exclude dependencies or advisories. Bun 1.4 cannot reset every inherited dependency-scope setting without also discarding registry configuration. Foxy therefore rejects a Bun audit when a loaded .npmrc or bunfig.toml excludes a dependency type required by the requested audit. Remove the restrictive setting, or use --no-dev when the only restriction is the development dependency graph. Audit preflight also requires UTF-8 configuration and canonical [install] table syntax; inline or array install tables, escaped keys or omit values, and multiline values inside [install] are rejected rather than interpreted heuristically. The preflight rejects restrictive declarations even when a later include or higher-precedence file would override them.

Manager timeout

Set a timeout in seconds for the frontend manager process:

{
  "config": {
    "foxy": {
      "manager-timeout": 420
    }
  }
}

Package merging without manager execution

Disable manager binary probing and execution while continuing to update package.json:

{
  "config": {
    "foxy": {
      "run-asset-manager": false
    }
  }
}

In this manifest-only mode, Foxy does not probe manager binaries, run install or update commands, or remove existing node_modules/@composer-asset/* installations during npm reconciliation. Generated Composer asset manifests and the root package.json are still updated. An explicit composer foxy:audit remains available and validates and runs the selected manager because it represents a direct user request.

Fallbacks

Both fallbacks are enabled by default. They can be controlled independently:

{
  "config": {
    "foxy": {
      "fallback-asset": true,
      "fallback-composer": false
    }
  }
}
  • fallback-asset restores the project package.json when package merging or manager execution fails.
  • fallback-composer restores the captured lock data and installed Composer dependencies for any exception or non-zero manager result during asset solving.

Foxy rethrows the original solve error when Composer restoration succeeds. If restoration also fails, Foxy reports the rollback failure and retains the original error as the previous exception. Disabled fallbacks do not create snapshots.

Composer lock and vendor state are captured at Composer's pre-operations-exec event. This is not a fully atomic transaction for composer require or composer remove: Composer may update the root composer.json before that event, and Foxy does not retain its previous bytes. Inspect and, when necessary, revert composer.json after a failed command.

Mock package directory

By default, Foxy writes local mock packages under <vendor-dir>/php-forge/composer-asset/. Override the location with:

{
  "config": {
    "foxy": {
      "composer-asset-dir": "runtime/foxy-assets"
    }
  }
}

Foxy recursively resets this directory during each solve. To prevent deletion outside Foxy-owned storage, it rejects:

  • An empty path, filesystem root, project root, vendor root, or a parent directory that contains either protected root.
  • A symbolic link used as the asset directory.
  • An existing, non-empty custom directory without Foxy's .foxy-managed ownership marker.

A new or empty custom directory is accepted and receives the marker automatically. Before upgrading an existing custom directory, verify that it contains only generated Foxy data, remove its contents, and let Foxy recreate and mark it.

Package selection

Foxy normally processes installed packages that require Foxy or declare extra.foxy=true. The root project can include or exclude package names with glob patterns or regular expressions:

{
  "config": {
    "foxy": {
      "enable-packages": {
        "foo/*": true,
        "foo/legacy-*": false,
        "/^acme\\/theme-/": true
      }
    }
  }
}

When no package must be excluded, a list is sufficient:

{
  "config": {
    "foxy": {
      "enable-packages": ["foo/*", "/^acme\\/theme-/"]
    }
  }
}

Patterns are evaluated in declaration order; the first matching pattern determines the result.

package.json directory

In the root application, root-package-json-dir controls the package.json read/write path and manager working directory:

{
  "config": {
    "foxy": {
      "root-package-json-dir": "web"
    }
  }
}

Relative root-project paths are resolved from the Composer project directory. Absolute paths and filesystem roots are supported.

In an installed Composer library, the same option is resolved relative to that library's installation directory and identifies the directory containing its embedded package.json. The resolved manifest must remain inside the library's Composer installation directory.

Next steps