Add Moox Package

Add a package to this monorepo-consuming project

This project consumes moox/* packages directly from the monorepo (mooxphp/moox) via Composer path repositories — no Packagist, no release. This skill performs the complete sequence to add one, avoiding the pitfalls that otherwise cause CI/deploy failures.

This skill ships with the devlink package (resources/boost/skills/add-moox-package/) and is installed via Laravel Boost. Background and rationale live in the devlink docs. This skill is the actionable checklist.

Step 0 — Identify which kind of package

Two cases, different steps. Determine which before doing anything:

• A Moox monorepo package (moox/<name>) — lives in the mooxphp/moox monorepo, fetched/symlinked into packages/. Managed via config/devlink.php. Most common case.
• The project's own package (a local/committed package, e.g. acme/<name>) — committed in this repo under packages/, not from the monorepo.

If unclear, ask the user. Also confirm the exact package name and the folder name (they can differ, e.g. a package acme/components may live in folder components or acme-components).

Case A — Add a Moox monorepo package

A1. Activate it in config/devlink.php

Find the package's entry under 'packages' (the array key is the folder name, e.g. 'address'). Set it active:

'<folder>' => [
    'active' => true,        // was false
    'path' => $public_base_path.'/<folder>',
    'type' => 'public',
],

If the entry doesn't exist, the package may not be a public monorepo package — stop and confirm with the user.

A2. Symlink it locally

php artisan moox:devlink

This adds a path entry to composer.json — but only with symlink: true, without the versions option. The next step adds the missing piece.

A3. Add/fix the composer.json entries

This is the critical step. Two parts:

require — add the package on *:

"moox/<name>": "*"

repositories — the path entry MUST include versions forcing dev-main. moox:devlink does not add this, so add it manually:

{
    "type": "path",
    "url": "packages/<folder>",
    "options": {
        "symlink": true,
        "versions": { "moox/<name>": "dev-main" }
    }
}

Why versions is non-negotiable: without it, Composer derives the version from the surrounding project branch (dev) → dev-dev, but the monorepo packages require each other as dev-main, so resolution fails with ... requires moox/core dev-main ... do not match your constraint. The versions option forces dev-main. Add it for every moox path entry; if other entries are missing it, add it there too (start with moox/core).

A4. Regenerate the package list

php artisan moox:devlink-export

This rewrites .github/moox-packages.txt from the active type: public packages in config/devlink.php. CI and the deploy script read this file. Confirm the new package now appears in it.

A5. Resolve

composer update "moox/*"

Expect a clean resolution. If you see dev-dev errors, a versions option is missing (go back to A3). If you see "could not find package", the folder isn't in packages/ (was A2 run? is the folder name correct?).

A6. Verify the app still boots (catches deploy-time failures early)

php artisan optimize:clear
php artisan optimize

optimize runs route:cache, view:cache, config:cache — the same steps the deploy runs. These surface problems invisible in normal local dev:

• Unable to prepare route [...] Another route has already been assigned name [...] → duplicate route name (often in the new package); find with grep -rn "<name>" packages/ app/ routes/ and make one unique.
• Unable to locate a class or view for component [...] → a referenced component/class from a package that isn't registered/installed.

Resolve any failure here before committing — otherwise the deploy fails at this step.