Nativekitv5 Laravel Package

Getting Started

jeffersongoncalves/nativekitv5 is a Filament v5 starter/UI kit — the package version deliberately tracks Filament's own version number (the 5.10.1 release is literally "Bump Filament to v5.10.1"). Treat it as a theme + panel scaffold you lay on top of a fresh Filament v5 install, not something you build around.

Minimal path:

1. composer require jeffersongoncalves/nativekitv5
2. Publish the package's config and frontend assets: php artisan vendor:publish --provider="JeffersonGoncalves\NativeKitV5\NativeKitV5ServiceProvider" (check php artisan vendor:publish output for the exact tag — config, views, and theme assets are usually separate tags).
3. Install JS deps with pnpm, not npm — the repo builds with pnpm and keeps dependency overrides in pnpm-workspace.yaml. Then pnpm run build.
4. Wire the kit into your panel provider (->viteTheme(...) or the kit's registration method) and run php artisan filament:assets plus php artisan optimize:clear.

Where to look first: the package's panel provider registration and its published config/nativekit.php (or similarly named). That file tells you which layout, navigation style, and asset paths are configurable. Then look at a published Blade view to see how the shell is composed — that's the fastest way to learn what the kit actually gives you beyond stock Filament.

First real use case: a mobile-first Filament panel — app-like shell, bottom/tabbed navigation, safe-area handling — where you want the chrome done for you and you only write resources and pages.

Implementation Patterns

Pin the package to your Filament version. Because the package version mirrors Filament's, the healthiest workflow is to keep filament/filament and jeffersongoncalves/nativekitv5 on the same minor line in composer.json and upgrade them together in one PR. This release (a pure dependency bump) is exactly the kind of change that should ride along with a Filament patch upgrade, not be deployed on its own schedule.

One panel provider, kit applies to the panel. Register the kit inside PanelProvider::panel() rather than globally, so you can run a "native" panel for the app surface and a stock panel for admin. Use panel-scoped ->colors(), ->font(), and the kit's layout options so the two don't bleed into each other.

Customize via overrides, not forks. Publish the views/blade components you want to change and edit the published copies; keep the vendor tree pristine so composer update is safe. Same for the theme: extend the kit's entry point in your own resources/css/app.css rather than editing files under vendor/.

Frontend build hygiene. The kit patches shell-quote and source-map-js through pnpm overrides. In 5.10.1 those overrides moved from package.json into pnpm-workspace.yaml — if your app copies the kit's package.json, don't also carry a duplicate pnpm.overrides block or you'll get conflicting resolution. Commit pnpm-lock.yaml and build in CI with the same pnpm major version (corepack enable + the packageManager field).

Composition with Filament features. Combine the kit's shell with Filament's SPA mode (->spa()), tenant support, and render hooks. Render hooks are usually the cleanest integration point — inject nav items or action buttons without touching the kit's layout files.

Testing. Filament panel tests (Livewire/Pest) should still work; add one smoke test that renders your panel's dashboard route so a dependency bump that breaks the shell fails in CI rather than in a user's hands.

Gotchas and Tips

• Version numbers are not independent. nativekitv5 5.10.1 ≈ Filament 5.10.x. If you upgrade Filament to 5.12 but leave the kit on 5.10, the mismatch surfaces as broken styling or missing blade components, not as a clear error. Bump both, or neither.
• npm silently ignores the pnpm overrides. The security patches for shell-quote and source-map-js are pnpm-specific. Using npm install in your app won't apply them — you'll get a clean install and an unpatched tree. Enforce pnpm ("packageManager" + CI check) if you care about that.
• Moving overrides to pnpm-workspace.yaml is a copy-paste trap. Anyone who copied the old package.json snippet into their app keeps stale overrides after upgrading. Re-check your override block after every kit upgrade; duplicate/conflicting overrides produce confusing resolution errors.
• The "Bump Filament to v5.10.1" title is doing the work, not the changelog. The listed PRs are all Dependabot and patch-override noise. For a release like this the meaningful question is "which Filament version does this require?" — read the composer.json constraint in the tag, not the release notes. The jump from 5.8.4 to 5.10.1 in the compare link means ~2 Filament minors of upstream changes are bundled in; skim Filament's own 5.9/5.10 upgrade notes before bumping.
• Asset publishing after upgrade is easy to forget. After any kit bump: re-publish changed assets, rebuild with pnpm, and php artisan filament:assets + view:clear. A stale published theme is the #1 cause of "the update did nothing."
• Don't rely on the repo's dev tooling in production. vite, shell-quote, and the other bumped entries are dev dependencies for building the theme; your app only needs the compiled CSS/JS. Keep the kit's node toolchain in dev-only, build artifacts in CI.
• Extension points to prefer, in order: config file → published views → render hooks → custom panel provider method → forking. Each step down costs you upgrade ergonomics.
• Debugging the shell: if layout looks half-applied, check that the panel provider actually registered the kit (dump the panel config), then confirm the compiled theme manifest exists at public/build/manifest.json with the expected entry name, then check for a duplicate @vite/viteTheme call in your provider.