README

Foxy

Foxy is a Composer plugin that aggregates frontend dependencies declared by Composer packages into one package.json and delegates installation to Bun, npm, pnpm, or Yarn.

Features

Requirements

PHP 8.3 or later.
Composer 2.10.2 or later.
One supported frontend manager for automatic manager execution or explicit security audits:
- Bun ^1.4.0.
- npm >=10.9.8 with a Node.js version supported by the selected npm release.
- pnpm ^11.23.0 with Node.js >=22.13.0.
- Yarn ^4.18.0 with Node.js >=18.12.0; use a Node.js release that still receives security updates.

Installation

Authorize the Composer plugin and install Foxy 0.3:

composer config allow-plugins.php-forge/foxy true
composer require php-forge/foxy:^0.3

Selecting a manager explicitly is recommended for reproducible local and CI behavior:

{
  "require": {
    "php-forge/foxy": "^0.3"
  },
  "config": {
    "allow-plugins": {
      "php-forge/foxy": true
    },
    "foxy": {
      "manager": "npm"
    }
  }
}

Valid manager values are bun, npm, pnpm, and yarn. When automatic manager execution is enabled and manager is omitted, Foxy first looks for one recognized native lockfile and then checks available executables. Configure the manager explicitly when the project contains lockfiles from more than one manager.

During automatic Composer processing, run-asset-manager=false prevents Foxy from requiring or probing a manager binary. Automatic selection uses the single recognized lockfile when present, or npm as the manifest adapter when no lockfile exists. An explicit composer foxy:audit still validates and runs the selected manager.

Frontend security audit

Audit the exact frontend dependency graph recorded by the selected manager's lockfile:

composer foxy:audit
composer foxy:audit --format=summary --no-dev --audit-level=high

Foxy normalizes the current npm, pnpm, Yarn, and Bun audit reports and identifies the affected package, advisory, severity, vulnerable range, and CVE identifiers when GitHub maps the advisory to a CVE. The command returns 0 when no advisory meets the configured threshold, 1 when at least one does, and 2 when the audit cannot be completed reliably. See the usage guide for formats and CI examples.

Quick start

Composer-based PHP application

Foxy is framework agnostic and works with any Composer-based PHP application that meets the requirements above. No framework integration or application template is required. Composer packages that opt in contribute their frontend dependencies, and Foxy merges them whenever Composer installs or updates the project.

Project with package.json under web/

Composer may remain at the repository root while frontend tooling runs from web/:

{
  "config": {
    "allow-plugins": {
      "php-forge/foxy": true
    },
    "foxy": {
      "manager": "npm",
      "root-package-json-dir": "web"
    }
  }
}