# Getting started

> Foxy is a Composer plugin that aggregates frontend dependencies declared by installed Composer packages.

1. [Introduction](#introduction)
2. [Requirements](#requirements)
3. [Installation](#installation)
4. [Manager selection](#manager-selection)
5. [Next steps](#next-steps)

## Introduction

Foxy is a Composer plugin that aggregates frontend dependencies declared by installed Composer packages. It creates
local package representations and lets Bun, Deno, npm, pnpm, or Yarn resolve and install those dependencies with its
native solver, or resolves and installs them itself with the `native` manager when no JavaScript manager is wanted.

An embedded `package.json` should be treated as an independently versioned frontend package. Foxy uses the Composer
package version only when the embedded package does not declare its own version.

## Requirements

| Requirement | Supported version or value                                                     |
| ----------- | ------------------------------------------------------------------------------ |
| PHP         | 8.3 or later                                                                   |
| Composer    | 2.10.2 or later                                                                |
| Bun         | `^1.4.0`                                                                       |
| Deno        | `^2.9.7`                                                                       |
| npm         | `>=10.9.8`; use a Node.js version supported by the selected npm release        |
| pnpm        | `^11.23.0`; Node.js `>=22.13.0`                                                |
| Yarn        | `^4.18.0`; Node.js `>=18.12.0` on a release that still receives security fixes |
| Git         | Required only for Git-based dependencies                                       |
| `native`    | No frontend manager; PHP with the `zlib` extension                             |

The frontend manager requirements apply to automatic manager execution and explicit security audits. Manifest-only
Composer processing does not require a manager binary, but `composer foxy:audit` does with a binary manager. The
`native` manager needs no binary at all, not even to audit; see [Native manager](/docs/extensions/foxy/config/index.md#native-manager).

## Installation

Composer plugins execute code during Composer operations. Authorize Foxy explicitly before installing it:

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

The plugin is installed in the configured Composer vendor directory, normally `vendor/php-forge/foxy`.

### Verify the installation

Check the installed package version before configuring and installing project assets:

```bash
composer show php-forge/foxy
```

## Manager selection

Set `config.foxy.manager` to `bun`, `deno`, `native`, `npm`, `pnpm`, or `yarn` when reproducible manager selection is
required. When manager execution is enabled and the option is omitted, Foxy looks for one recognized lockfile and then
for an available manager executable. Multiple recognized lockfiles require explicit selection. The `native` manager is
never chosen by availability: Foxy uses it when `manager` is `native` or when `foxy.lock` is the single recognized
lockfile.

During automatic Composer processing, `run-asset-manager=false` makes Foxy select from a single lockfile or use npm as
the manifest adapter without probing executables. An explicit `composer foxy:audit` still probes and runs the selected
manager.

Commit the selected manager's own lockfile and use the same explicit manager in local development and CI.

## Next steps

- ⚙️ [Configuration reference](/docs/extensions/foxy/config/index.md)
- 💡 [Usage guide and examples](/docs/extensions/foxy/usage/index.md)
- 🤖 [AI agents guide](/docs/extensions/foxy/agents/index.md)
- ⬆️ [Upgrade guide](https://github.com/php-forge/foxy/blob/main/UPGRADE.md)

[Back to documentation](/docs/extensions/foxy/index.md#documentation)