Core Laravel Package

Getting Started

cms-orbit/core is a Laravel package that bridges a PHP backend with a TypeScript frontend: it generates the paths aliases your app needs so imports like @cms-orbit/core (and other packages exposing an index.ts / index.tsx / index.js) resolve correctly at build time.

Minimal setup on 4.6.2:

1. composer require cms-orbit/core (add laravel/octane yourself if you run Octane — it is only in suggest, not required).
2. Run php artisan orbit:frontend-sync. This is the single entry point; it writes aliases into your tsconfig.json.
3. Open tsconfig.json and confirm the generated compilerOptions.paths entries exist, then run your frontend build/typecheck (tsc --noEmit is the fastest signal).

Upgrading from 4.6.1 or earlier:

composer update cms-orbit/core
php artisan orbit:frontend-sync

If your tsconfig.json contains comments (JSONC), the command will not rewrite it — copy the paths block it prints into the file by hand. That caveat is called out in the 4.6.2 notes and is the most common first-run surprise.

First use case to validate: register a custom component that imports directly from @cms-orbit/core and confirm your editor/tsc resolves it without a red squiggle. Before 4.6.2 that bare-alias import was the exact thing that failed.

Implementation Patterns

Run sync as a post-update step, not a one-off. Add it to your Composer scripts so it can never drift from vendor/:

"scripts": {
  "post-update-cmd": ["@php artisan orbit:frontend-sync"]
}

Commit the resulting tsconfig.json. The command mutates a tracked file; treat the diff like a lockfile change so reviewers see alias churn.

CI drift check. Run php artisan orbit:frontend-sync in CI and fail if git diff --exit-code tsconfig.json is non-empty. This catches the case where a dependency bump introduces a new aliased package but nobody re-ran the command locally.

Custom component registration. The canonical integration point for the 4.6.2 fix:

import { registerComponent } from '@cms-orbit/core';

Both the automatic sync and the human-readable guidance block now derive aliases from the same path-generation function (this was inconsistent in 4.6.1, where only the printed instructions got the fix). Practical consequence: if you hand-copied paths from the old manual block, re-run the command so auto-sync emits the identical set.

Deploy pipelines. Run orbit:frontend-sync before the frontend build step in the same job, after composer install --no-dev. It's a build-time artifact generator, so ordering matters more than caching.

Multi-package repos. Any workspace package that ships an index.ts/index.tsx/index.js at its root gets a bare alias. If you maintain internal packages, matching that layout gets you automatic alias coverage for free.

Gotchas and Tips

• Commented tsconfig.json is not auto-merged. This is the headline gotcha. The command prints the paths it would have written; you paste them in. Consider keeping a comment-free tsconfig.json (or a comment-free base file extended via "extends") if you want full automation.
• Stale aliases after composer update. Nothing regenerates automatically unless you wire it up. A missing bare alias manifests as a TypeScript module-resolution error, not a PHP error — so it surfaces in the frontend build, often on someone else's machine.
• Bare alias vs. deep import. The alias covers the package root (@cms-orbit/core). Deep subpath imports are not implied by this change; don't assume the fix generalizes.
• laravel/octane is a suggest, not a dependency. 4.6.2 finally added it to composer.json's suggest block. composer suggest output is informational only — Octane users still need to require it explicitly, and non-Octane users can ignore it entirely.
• Release history merge is a no-op for consumers. The 4.6.1 history was consolidated onto main with existing tags preserved. If you pin by tag, nothing changes; if you pin by branch, re-verify your lockfile resolves to a tag.
• Debugging alias output. If a path looks wrong, check what the command prints before it touches the file — the printed block is the same data the writer uses. Diff that against your tsconfig.json to tell "generator is wrong" from "file wasn't updated."
• Verification bar for this release. Package tests run on PHP 8.4 and 8.5 with Pint and TypeScript CI. If you're on PHP 8.3 or below, this release's support matrix doesn't cover you — check the package's composer.json constraints before upgrading.
• No breaking changes in 4.6.2. It's a patch release of fixes and metadata; upgrading is low-risk, and the only action item is re-running orbit:frontend-sync.