# Foxy

> Foxy is a Composer plugin that aggregates frontend dependencies declared by Composer packages into one package.json and delegates installation to Bun, Deno...

Package entry: `php-forge/foxy`. Requires PHP `^8.3`. Checked 2026-10-27. [View the entry in the package directory](</docs/packages/php-forge/foxy/index.md>)

**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

![Foxy features: dependency aggregation, native manager support and selection, flexible roots, protected mock directories, failure recovery, defensive I/O, and stable execution.](/docs/_astro/features.Cr52m7uF.svg)

## 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:

```bash
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:

```json
{
  "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):

```json
{
  "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](/docs/extensions/foxy/config/index.md#native-manager) for its scope.

## Frontend security audit

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

```bash
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](/docs/extensions/foxy/usage/index.md#security-auditing) 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/`:

```json
{
  "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](/docs/extensions/foxy/getting-started/index.md)
- ⚙️ [Configuration reference](/docs/extensions/foxy/config/index.md)
- 💡 [Usage guide and examples](/docs/extensions/foxy/usage/index.md)
- 🔌 [Events reference](/docs/extensions/foxy/events/index.md)
- ❓ [Frequently asked questions](/docs/extensions/foxy/faqs/index.md)
- 🤖 [AI agents guide](/docs/extensions/foxy/agents/index.md)
- ⬆️ [Upgrade guide](https://github.com/php-forge/foxy/blob/main/UPGRADE.md) and [migration guide](/docs/extensions/foxy/migration/index.md)
- 🧪 [Testing guide](/docs/extensions/foxy/testing/index.md)

## AI assistance

AI agents can use the [documentation index](https://yii2-framework.github.io/docs/llms.txt) to discover pages and fetch
a page's Markdown version by appending `index.md` to its URL. The
[AI agents guide](https://yii2-framework.github.io/docs/project/ai-agents/) covers skill installation, client setup, and
verification.

- 🤖 [`php-forge-foxy` skill](/docs/extensions/foxy/agents/index.md): 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](#documentation), [skill source](https://github.com/php-forge/foxy/blob/main/skills/php-forge-foxy/SKILL.md), source PHPDoc, and
[changelog](https://github.com/php-forge/foxy/blob/main/CHANGELOG.md).

## Our social networks

[Follow on X](https://x.com/Terabytesoftw)

## License

[License](https://github.com/php-forge/foxy/blob/main/LICENSE)

## Package

- Source code and issues: [php-forge/foxy](https://github.com/php-forge/foxy). Star the repository if the package is useful to you.
- Composer package: [php-forge/foxy](https://packagist.org/packages/php-forge/foxy).
- Changelog: [CHANGELOG.md](https://github.com/php-forge/foxy/blob/main/CHANGELOG.md).