Foxy

Foxy is a Composer plugin that aggregates frontend dependencies declared by Composer packages into one package.json and delegates installation to Bun, Deno, npm, pnpm, or Yarn, or installs them itself without any JavaScript manager.

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.
  • Deno ^2.9.7.
  • 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.
• Or no frontend manager at all: the native manager installs the dependencies with PHP and the zlib extension.

Installation

Authorize the Composer plugin and install Foxy 0.4:

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

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

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

Valid manager values are bun, deno, native, npm, pnpm, and yarn. When automatic manager execution is enabled and manager is omitted, Foxy first looks for one recognized 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.

Without Node.js

Set manager to native and Foxy resolves the merged package.json against the npm registry, downloads the tarballs, verifies their integrity, and extracts them into a flat node_modules directory using PHP alone (or into the directory native-install-dir names):

{
  "config": {
    "foxy": {
      "manager": "native"
    }
  }
}

The selected versions are recorded in foxy.lock; commit it so that composer install reinstalls the same versions without any registry metadata request. Tarballs come from the Composer cache, or are downloaded again from the URLs recorded in the lock when the cache is empty. The native manager keeps one version per package, like asset-packagist, and does not run lifecycle scripts. native-install-dir moves the install directory, for example to vendor/npm-asset for Yii 2's default @npm alias. See the native manager reference for its scope.

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, Bun, Deno, and native 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. With Deno and the native manager, --no-dev is rejected because neither can exclude development dependencies. 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"
    }
  }
}

Foxy reads and writes web/package.json and runs the selected manager from web/. Relative paths are resolved from the Composer project directory.

Documentation

• 📚 Getting started
• ⚙️ Configuration reference
• 💡 Usage guide and examples
• 🔌 Events reference
• ❓ Frequently asked questions
• 🤖 AI agents guide
• ⬆️ Upgrade guide and migration guide
• 🧪 Testing guide

AI assistance

AI agents can use the documentation index to discover pages and fetch a page's Markdown version by appending index.md to its URL. The AI agents guide covers skill installation, client setup, and verification.

• 🤖 php-forge-foxy skill: configure asset integration and audits.

Match the documentation to the installed Foxy revision. If the hosted documentation is unavailable or does not match, use the repository guides, skill source, source PHPDoc, and changelog.

Package information

Project status

Our social networks

Built with AI

License