Frontend Laravel Package

Getting Started

luminix/frontend is a small package (literally src/, config/frontend.php and views/embed.blade.php) that exposes your Eloquent models to a Luminix frontend as a manifest, and gives you a single Blade view to embed the result. Treat it as a data-contract package, not a UI kit.

Minimal steps:

1. composer require luminix/frontend. It pulls luminix/backend transitively, which in turn brings spatie/laravel-model-info and the Luminix\Backend\Facades\Finder facade. Those are not optional — the manifest service uses both.
2. Publish the config and the bundled agent skill:

   php artisan vendor:publish --tag=luminix-skill
   

   Publishing luminix-skill is the single most useful thing you can do on day one. It drops an English skill/SKILL.md plus skill/references/ into your app. That is the real documentation for consuming the package — the README.md on Packagist is Portuguese and aimed at people evaluating the repo.
3. Inspect config/frontend.php. Almost every day-to-day decision (which models are exposed, how they are filtered, what the embed view receives) is a config key, so read the file before writing any code.
4. Drop views/embed.blade.php into a layout with @include('frontend::embed') and load a page. If the manifest endpoint returns 500, you almost certainly have not configured a model or the guest filter yet, not a broken install.

First use case to aim for: expose one model (say Post) to the manifest, render the embed view on a single route, and confirm the payload in the network tab. Do not start by exposing your whole schema — the manifest is an API surface you will have to keep stable.

Implementation Patterns

Treat the manifest as your frontend API. The models you expose and the fields you allow through are the contract. Add models deliberately and review the diff of the manifest output when you do — this is the closest thing you have to an API schema.

Model selection via config + Finder. The inclusion list comes from config/frontend.php, and resolution goes through Luminix\Backend\Facades\Finder and Spatie\ModelInfo. Use per-model field selection (ModelInfo-driven) rather than exposing every column — especially on models with password, tokens, or internal flags. If a field should not leave the server, exclude it at the model/config layer, not in the frontend.

Reducers are named contracts. Frontend state reducers are referenced by name. Renaming a reducer or a payload key is a breaking change for the SPA even though PHP won't complain. Keep names stable, and if you must rename, add the new key alongside the old one for one release.

Embedding. views/embed.blade.php is the seam between Laravel and the frontend runtime. Wrap it in your own layout, pass any bootstrap data (user id, locale, feature flags) via the view, and keep auth-sensitive data out of the embed payload — hydrate it through an authenticated endpoint instead.

Guest vs authenticated visibility. The manifest can suppress the guest filter; do not rely on that in tests (see Gotchas). For real behavior, assert it over HTTP with TestCase::simulateHttpContext() or a Dusk/feature request, not with a console-invoked service.

Production caching. Manifests are mostly static per deploy. Cache the output and bust it on deploy (or on a config/model change) rather than rebuilding per request. If you cache, make sure the cache key includes anything that affects visibility, otherwise you will leak fields across user types.

Keep the agent skill in sync. After upgrading the package, re-run:

php artisan vendor:publish --tag=luminix-skill --force

A stale skill/ copy in your app will describe payload keys and reducer names that no longer exist — and any agent or teammate reading it will write code against a phantom API.

Gotchas and Tips

• runningInConsole() defeats guest-visibility tests. ManifestService::make() suppresses the guest filter whenever it detects a console context, which is always true under PHPUnit. A test that "proves" guests are filtered will pass while the app leaks. Use TestCase::simulateHttpContext() in the package's own testbench setup, and hit a real HTTP route in your app's tests.
• The backend dependency is load-bearing. ManifestService needs spatie/laravel-model-info and the Finder facade, both of which arrive through luminix/backend. Constraint conflicts in that package break the manifest, not just model introspection — expect failures far from the actual cause.
• README.md is Portuguese; skill/SKILL.md is English. They serve different audiences and are not mirrors. If you are an English-speaking team, publish the skill and read that; do not try to infer behavior from the README.
• Config keys are public API. Per the repo's own rules, a change to a payload key, manifest field, config key, reducer name, or artisan flag is externally observable and should be documented. That cuts both ways for you: assume anything you change in config/frontend.php is a versioned contract, not local tuning.
• Publish tags and artisan flags are not obvious from the README. Enumerate them rather than guessing:

  php artisan list | grep -i luminix
  

• Zero stars, zero dependents. This is a young, single-consumer package. Pin the version ("luminix/frontend": "1.x-dev" or an exact tag), read src/ when behavior is unclear — it is small enough to read in one sitting — and check the release notes between bumps. Releases are automated from commit subjects ((MAJOR)/(MINOR)/patch), so a patch bump can still carry a payload change; skim the diff.
• Extension point is narrow by design. There is no event bus or macro system advertised; the intended customization surfaces are the config file and the Blade embed view. If you find yourself needing to subclass ManifestService, you are probably fighting the package — reconsider whether the model belongs in the manifest at all.
• Contributing or vendoring? Note that the Luminix\Frontend\Tests\ → tests/ autoload entry in composer.json is dead; real tests live in workbench/app/Tests/Feature under orchestra/testbench. composer lint is declared but unusable (phpstan is not in require-dev). Run composer test instead.