# Frequently asked questions

> Foxy 0.4 requires PHP 8.3 or later and Composer 2.10.2 or later. See the requirements.

## Which PHP and Composer versions are required?

Foxy 0.4 requires PHP 8.3 or later and Composer 2.10.2 or later. See the [requirements](/docs/extensions/foxy/getting-started/index.md#requirements).

## Why use Foxy instead of documenting frontend dependencies manually?

A PHP library can ship a `package.json`, but Composer does not merge that file into the consuming application. Without
automation, every application must copy dependency names and constraints manually and keep them synchronized with each
library release.

Foxy creates local frontend package representations for eligible Composer dependencies, merges them into the project
`package.json`, and delegates version solving and installation to Bun, Deno, npm, pnpm, or Yarn, or performs both itself
with the `native` manager.

## How does package activation work?

An installed Composer package is eligible when it contains the expected package definition and at least one of these
conditions applies:

- It requires `php-forge/foxy`.
- It declares `extra.foxy=true`.
- The root project enables it through `config.foxy.enable-packages`.

The root project can also explicitly exclude a package through `enable-packages`.

## How are local frontend packages named and stored?

The Composer name is converted to the `@composer-asset/` scope. For example, `acme/theme` becomes
`@composer-asset/acme--theme`.

Mock package definitions are stored under `<vendor-dir>/php-forge/composer-asset/` by default. The project
`package.json` refers to those definitions with local `file:` dependencies. Configure `composer-asset-dir` to use a
different location.

## How does Foxy select a frontend manager?

Set `config.foxy.manager` to `bun`, `deno`, `native`, `npm`, `pnpm`, or `yarn` for deterministic selection. When it is
omitted and manager execution is enabled, Foxy first looks for one recognized lockfile and then for an available manager
executable. With execution disabled, it uses a single recognized lockfile or npm as the manifest adapter without probing
binaries. Multiple recognized lockfiles require explicit selection in either mode. The `native` manager is selected only
explicitly or through its `foxy.lock` file, never by availability. The choice is made when the first install, update, or
audit needs a manager, so other Composer commands neither probe executables nor report selection errors.

Explicit selection and a committed lockfile are recommended for CI.

## Can Foxy install frontend dependencies without Node.js?

Yes. Set `config.foxy.manager` to `native`. Foxy reads the merged `package.json`, resolves every dependency against the
npm registry with one version per package, downloads and verifies the tarballs, extracts them into `node_modules`, and
records the result in `foxy.lock`. PHP with the `zlib` extension is the only requirement. The native manager does not
run lifecycle scripts and does not create `bin` links. See [Native manager](/docs/extensions/foxy/config/index.md#native-manager) for the complete
scope.

## How can frontend dependencies be checked for known CVEs?

Run `composer foxy:audit`. Foxy audits the dependency graph from the selected manager's own lockfile. The default table,
plain, and JSON formats identify the affected package, advisory, severity, vulnerable range, and available CVE
identifiers. Use `--format=summary` for compact counts in CI or `--format=json` for a versioned machine-readable
document.

The registry's audit response commonly contains a GHSA but no CVE. Foxy resolves that relationship through GitHub's
public advisory API unless `--no-cve` or `--format=summary` is supplied. The lookups run concurrently through Composer's
HTTP downloader (at most 12 at once; `COMPOSER_MAX_PARALLEL_HTTP` changes the limit), and a `github-oauth` token in
Composer's `auth.json` applies to them. A lookup failure marks only its own advisory as unavailable without hiding the
security finding itself. See [Security auditing](/docs/extensions/foxy/usage/index.md#security-auditing) for options and exit statuses.

## Why is a dependency's package.json not detected?

Check the following:

1. The package uses one of the documented activation methods.
2. Its `package.json` exists at the package root or configured Foxy root.
3. The root application's `enable-packages` configuration does not exclude it.
4. When manager execution is enabled, the selected frontend manager is installed and allowed by its configured version
   constraint.

Composer must run before a standalone frontend manager command because Foxy creates the local package representations
during Composer install and update operations.

## What happens when the frontend manager fails?

When the manager throws or returns any non-zero status, Foxy reports the error and, by default, restores the previous
project `package.json`, Composer lock data, and installed Composer dependencies. The original manager error is rethrown
when restoration succeeds. If a restoration also fails, the rollback error retains the original error as its previous
exception.

Set `fallback-asset` or `fallback-composer` to `false` only when retaining partial state is intentional. A Composer
rollback installer failure is reported as a `RuntimeException` rather than being hidden.

The Composer fallback does not restore root `composer.json` bytes that Composer may change before Foxy takes its
snapshot. After a failed `composer require` or `composer remove`, inspect that file and revert unintended constraint
changes manually.

## Why does Foxy do nothing during Composer --dry-run?

Composer does not install, update, or remove packages during a dry run, so Foxy cannot build an accurate map from the
resulting installed packages. Run the real Composer operation to validate the complete Composer and frontend manager
operation; enabled fallbacks restore their captured state when asset solving fails.

## Can Foxy update package.json without installing frontend dependencies?

Yes. Set `config.foxy.run-asset-manager=false`. Foxy will update the package definition without probing or validating
the external manager, running its commands, or removing existing `node_modules/@composer-asset/*` installations during
npm reconciliation.

## Why are a dependency's scripts or devDependencies not copied?

Foxy mock packages contain only metadata needed for runtime dependency resolution and compatibility checks. Omitting
lifecycle scripts, executable definitions, `devDependencies`, and unrelated publishing metadata prevents an installed
Composer dependency from injecting those behaviors into the root frontend install.

Publish built assets with the Composer package, or configure intentional build commands and development dependencies in
the consuming application's own `package.json`.

## Why is my custom composer-asset-dir rejected?

Foxy deletes and rebuilds its mock package directory on every solve. It refuses filesystem, project, and vendor roots;
paths that contain either protected root; symbolic-link directories; and existing non-empty custom directories without
Foxy's `.foxy-managed` marker.

If the directory predates Foxy 0.3, verify that it contains only generated mock data, remove its contents, and rerun
Composer. Foxy accepts an empty custom directory and creates the ownership marker automatically. See
[Mock package directory](/docs/extensions/foxy/config/index.md#mock-package-directory).

## How can the PHP memory limit be increased?

See Composer's
[memory limit troubleshooting guide](https://getcomposer.org/doc/articles/troubleshooting.md#memory-limit-errors).

## How is Foxy related to Fxp Composer Asset Plugin?

[Fxp Composer Asset Plugin](https://github.com/fxpio/composer-asset-plugin) made frontend packages available through
Composer's solver. Foxy takes the opposite approach: Composer packages expose frontend definitions and a native frontend
manager performs frontend version solving and installation. Foxy is not backward compatible with Fxp Composer Asset
Plugin configuration.

## Next steps

- 📚 [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)
- ⬆️ [Upgrade guide](https://github.com/php-forge/foxy/blob/main/UPGRADE.md)

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