Console Laravel Package

Getting Started

Assegai Console is still a Composer-installed CLI (assegai) for PHP 8.4+ projects. 0.10.6 is additive: existing projects without webComponents.groups keep their current single-bundle discovery, output paths, and wc:list --json structure. No framework request-time changes are required.

Start with the same two install layers:

• Project-local copy via Composer, invoked as vendor/bin/assegai.
• Global copy as a personal convenience, updated with assegai global update or assegai -g update.

Verify identity after install or upgrade. These three should agree:

assegai --version
assegai version
assegai info

If all three agree on an older version, you are executing a stale binary selected by PATH, a shell alias, a wrapper, or a project-local install — not the package you just updated.

The new 0.10.6 feature to look at first is independent Web Component groups. Groups are opt-in. Configure them in assegai.json when you need separate bundles for different application surfaces — for example, public site components versus editor/admin components:

{
  "webComponents": {
    "groups": {
      "site": {
        "sources": ["src/WebComponents/Site"],
        "output": "public/js/site.min.js"
      },
      "editor": {
        "sources": ["src/WebComponents/Editor"],
        "output": "public/js/editor.min.js"
      }
    }
  }
}

Sources are explicit workspace-relative directories or .wc.ts files. Glob patterns are not supported.

First use case: run assegai wc:list --json before and after defining groups. Once groups are configured, components outside their source paths are excluded from discovery, so the inventory is the quickest way to confirm you have not accidentally dropped components.

Implementation Patterns

Keep project-local as the canonical install. Resolve vendor/bin/assegai in Composer scripts, Makefiles, and CI rather than relying on a bare assegai. Global installs drift; lock files do not.

"scripts": {
    "tooling:check": "vendor/bin/assegai --version",
    "wc:build": "vendor/bin/assegai wc:build"
}

Use one version probe per pipeline. assegai --version remains the simplest machine-readable check. Log it alongside composer show so a mismatch between the expected package and the executing binary is visible.

Model Web Component groups by deployment artifact, not by file convenience. A group owns its JavaScript output and the sibling CSS output emitted by esbuild. Build and watch selected groups with repeatable --group flags:

assegai wc:build --group=site
assegai wc:list --group=editor --json
assegai wc:watch --group=site --group=editor

Omitting --group selects all configured groups. Building a selected group leaves unselected groups’ artifacts unchanged.

Use separate groups for separate pages or application surfaces. Each group has its own entry file, component manifest, and esbuild dependency graph under .cache/assegai/groups/<name>/. That makes groups a good fit for a Laravel app that ships, for example, a public site bundle and an authenticated editor bundle. Applications remain responsible for including the right bundle — usually via Blade layout conditionals or a small asset helper.

Treat group membership as ownership boundaries. Group source memberships cannot overlap. Importing another group’s .wc.ts component is rejected. Shared ordinary TypeScript and CSS dependencies remain supported, so put shared non-component code outside the group source directories and import it normally.

Use wc:list --json in CI for inventory checks. Grouped JSON results additionally identify each component’s group. Existing non-grouped JSON structure is unchanged. If you parse the JSON, tolerate the added group field when groups are configured.

Build groups independently in CI where possible. A different group can still be built independently; locks prevent concurrent writers to the same group. If your pipeline only changes one surface, build that group and leave the others’ artifacts untouched.

Wire watch mode into local development deliberately. assegai wc:watch --group=site --group=editor coordinates the selected groups in one session, stops child processes together, and deactivates reload markers on shutdown. assegai serve --dev watches all configured groups.

Use --no-hot-reload for headless or controlled environments where you want watch builds and membership detection but no browser reload markers.

Upgrade both layers deliberately. Project-local copies update through Composer; global copies update with assegai -g update. After upgrading, re-run assegai info. Update checks and framework release recommendations come from the same installation identity that version reporting uses.

Rely on exit status, not output parsing. The CLI entrypoint now explicitly forwards the application’s return code when automatic exit has been disabled. Failed commands already returned nonzero status in previous releases. In scripts, check the exit code rather than grepping version or build output.

Gotchas and Tips

• Configuring groups changes discovery scope. Once webComponents.groups exists, components outside the configured source paths are excluded from discovery. Run assegai wc:list --json before and after adding groups to catch components that suddenly disappear from the manifest.

• No glob patterns. Sources must be explicit workspace-relative directories or .wc.ts files. Do not expect src/WebComponents/* to work. Unknown groups, conflicting artifact paths, and paths escaping the workspace are rejected.

• Overlapping group memberships are rejected. Plan source directories so each .wc.ts component belongs to exactly one group. Cross-group component imports are rejected; shared ordinary TypeScript and CSS dependencies are fine.

• Each group owns its CSS output too. esbuild emits sibling CSS for the group, and a previously emitted group stylesheet is removed when a successful build no longer emits it. If your Blade layouts hard-code a stylesheet path that is no longer emitted, you will get a missing asset rather than a stale file.

• Compiler/runtime builds and deployment uploads remain separate workflows. Assegai builds the bundles; your deployment process still needs to upload public/js/... and any emitted CSS. Do not assume a group build deploys assets.

• Watch sessions now stay alive when empty. Empty watch sessions no longer exit immediately. That is useful in development, but CI or process supervisors must handle long-running watch processes explicitly. Missing or removed directories are handled without filesystem warnings; unreadable existing directories raise their filesystem error instead of being silently ignored.

• Hot-reload membership detection has a polling interval. Component membership checks use the configured hot-reload polling interval and the existing watch tick. With the default interval, expect roughly one second for membership detection before build and browser-reload time. Idle checks do not read source contents or hash bundles.

• --no-hot-reload is not “no watch.” It keeps watch builds and membership detection active while suppressing browser reload markers. Use it when you want rebuilds but not live reload.

• CLI isolation is improved, but mixed environments still need verification. 0.10.6 keeps the executing Console installation’s classes authoritative after loading a workspace autoloader and before parsing package manifests. An older project-local Console can no longer substitute incompatible classes during extension discovery or subsequent commands. Other dependency namespaces retain their existing loader priority. If you previously worked around class substitution or bootstrapped the CLI from inside a Laravel app/test harness, re-test after upgrading both installations.

• Version identity problems are still environment problems. Debug with: vendor/bin/assegai --version; bare assegai --version; composer show <vendor>/<package>; composer global show; which -a assegai. If vendor/bin/assegai and bare assegai disagree, fix the environment rather than the package.

• Unknown remains a deliberate signal. If the executing installation’s metadata cannot be found, Console reports Unknown instead of borrowing another installation’s version. Typical causes are trimmed vendor directories, --no-dev production builds, and hand-copied binaries. Fix the install; do not parse around it.

• Windows was not tested for 0.10.6. CI passed on Ubuntu 24.04 with PHP 8.4.26 and 8.5.11, with focused local checks on macOS. If your team develops or deploys on Windows, smoke-test --version, version, info, grouped wc:build, wc:watch, and global update yourself.

• PHP 8.4+ remains non-negotiable. Do not add this to a project matrix that still tests PHP 8.2 or 8.3. Gate it behind the right CI images or keep it out of require-dev until the whole matrix moves.

• Prefer Composer-managed entrypoints as your extension surface. Custom vendor directories, symlinks, and Composer binary proxies are supported. Ad-hoc copying of the executable is still the pattern most likely to produce Unknown or a shadowed install.