Admin Laravel Package

Getting Started

The package ships an Inertia-powered admin panel (sidebar layout, mobile off-canvas header, login, profile page, and table components) built on @larasell-dev/ui. Treat v0.3.2 as still pre-1.0: the public surface is stabilizing, but config keys, NavigationItem, page resolution, and table behavior can still move between minors.

1. composer require larasell-dev/admin and confirm your app already runs Inertia — the package relies on Inertia page resolvers, shared validation errors, and an Inertia progress loader. A non-Inertia app is not the target.
2. Publish the package config/views (php artisan vendor:publish) and run any migrations shipped with it — the profile page and avatar upload imply user/profile persistence.
3. Confirm the front-end dependency resolves to @larasell-dev/ui 0.1.14 (v0.3.2 bumped it from the earlier 0.1.5 line). The login page relies on UI props like fullWidth, the loader relies on a UI color token, and table rendering now depends on newer UI table behavior.
4. Visit the admin route (typically /admin), log in through the package login page, and confirm the sidebar + mobile header render before touching anything else.
5. Open any package-provided table and verify the action column sits at the right edge — v0.3.2 explicitly fixed this (#85).

Where to look first, in order: the package service provider (routes, middleware, guard, route prefix), the config file (navigation registration, layout options), then NavigationItem — it remains the main public extension surface — and finally any table/action-column configuration if you render custom admin tables.

First real use case: register one NavigationItem pointing at one of your own Inertia pages, confirm it appears in the sidebar and mobile off-canvas nav, then render a simple package table on that page and check the action column alignment. That loop exercises routing, layout, navigation, and the table surface changed in v0.3.2.

Implementation Patterns

Register navigation declaratively. Build your sidebar from NavigationItem objects rather than editing package views. The improved misconfiguration errors from the 0.1.x line should still be your first debugging stop for invalid route names, missing labels, or bad icons.

Let the package own the chrome. Custom admin pages should render inside the provided layout (sidebar + mobile header), not re-implement it. Duplicating the shell is the fastest way to diverge on upgrade, especially around the mobile header and fixed-position layering.

Extend the profile page, don't replace it. You get name/email updates and avatar upload for free. Add fields via the package's form/controller extension points where available, and keep your own user-update logic out of a parallel route so the user menu and profile stay consistent.

Read validation errors from shared props. The package shares validation errors with admin pages, so custom pages can rely on the standard Inertia errors prop. If you already share errors yourself in HandleInertiaRequests, keep the shape identical and avoid clobbering package props.

Reuse @larasell-dev/ui for custom screens. Using the UI kit's Button (including fullWidth), form controls, color tokens, and table primitives keeps your pages visually consistent and inherits theme changes. Since v0.3.2 moved the UI package to 0.1.14, use the UI version the admin package pins rather than an older lockfile resolution.

Use package tables for action columns. v0.3.2 fixed keeping the table's action column at the right edge. If you build custom tables or custom action columns, model them on the package table conventions instead of hand-rolling sticky/absolute positioning — that is exactly where the regression lived.

Keep the Inertia page resolver conventional. The resolver is typed and expects a predictable pages directory/glob. If you customize page resolution, keep components in the location the package expects or explicitly configure the resolver rather than patching it ad hoc.

Local/dev workflow. The repo includes an Amp orb that serves the panel over HTTPS. Mirror that locally (Herd/Valet/Sail with TLS) if you're testing secure cookies, asset URLs, or anything guard/session related — mixed http/https is a common source of phantom auth bugs.

Gotchas and Tips

• Pre-1.0, pin exactly. At v0.3.2 the NavigationItem API, config keys, page resolver, and table/action-column markup are all still candidates for change. Pin the admin package and @larasell-dev/ui to exact versions and read changelogs before bumping.
• UI/package version pairing. v0.3.2 pins @larasell-dev/ui to 0.1.14. A mismatched UI version surfaces as missing props (fullWidth), undefined color tokens, or table layout regressions rather than a clear error. If the action column looks wrong after an upgrade, check the UI version first.
• Action column alignment is table-surface specific. The v0.3.2 fix (#85) applies to the package table's action column. Custom tables that reimplement sticky/right-edge behavior can still drift, especially with many columns or responsive wrappers.
• Loader color is a token, not CSS. Overriding the Inertia progress bar color means overriding the UI color token the package references; a plain CSS override will lose to it.
• Guard mismatch causes redirect loops. The package's styled login page and your auth middleware must agree on the guard. If login succeeds but you bounce straight back, check the guard name in the package config against your config/auth.php.
• Avatar upload failures are usually environmental. Verify the configured filesystem disk, php artisan storage:link, and upload_max_filesize/post_max_size. These fail quietly and look like a UI bug.
• Don't double-share errors. Now that the package shares validation errors with admin pages, a custom HandleInertiaRequests that also shares errors can produce conflicts or stale errors across admin/non-admin pages.
• Watch z-index around headers and tables. The mobile-header/backdrop fixes and the action-column fix both imply fixed-position/sticky layering in the shell and table. Custom sticky toolbars, table action menus, or modals layered above the admin layout are the likely regression point.
• Debugging checklist: php artisan route:list --path=admin for route/name sanity, Inertia devtools for page props, published views for template overrides, the NavigationItem exceptions for nav config, and the package table markup for action-column issues. php artisan about is a quick way to confirm the package and its providers are loaded.
• Extension points to prefer: published config, published views/layout components, NavigationItem registration, the profile page, and the package table/action-column conventions. Prefer these over forking package classes — at 0.3.x you'll still be re-merging otherwise.