Nativekit Laravel Package

Getting Started

Treat NativeKit as a starting point, not a library you bolt on. The description sells it as a zero-dependency helper bundle, but the release history (Filament 3.3.56, NativePHP, panel providers, user/admin packages) makes clear it is a Laravel 13 + Filament starter kit targeting packaged desktop apps. Your first hour should be spent confirming which of those two things you actually installed — check composer.json for filament/filament, nativephp/electron (or nativephp/laravel), and the user/admin packages referenced in PR #100. If none are there, you have the helper package and the rest of this document's desktop guidance does not apply.

Minimal path for the starter-kit case:

1. Clone the skeleton or composer require jeffersongoncalves/nativekit into a Laravel 13 app of the matching version.
2. Publish what the service provider offers and run the database setup:

   php artisan vendor:publish --provider="Jeffersongoncalves\Nativekit\NativekitServiceProvider"
   php artisan migrate --seed
   

3. Confirm the Filament panel resolves. In 3.3.x the panel's user model, resources and login page come from the user/admin packages, not from NativeKit itself. Open your panel provider and verify discoverResources() / discoverPages() paths point at something that actually exists.
4. First end-to-end use case: log in as the seeded admin, open the user resource, create and edit a record. That single flow exercises auth, panel registration, policies and the user/admin split at once — if it works, your scaffold is sound.

Where to look first, in order: the service provider (what it publishes and registers), the panel provider (resources, pages, widgets), and config/nativekit.php if it exists. Read those three before touching any generated code.

Implementation Patterns

Keep customisations in App\, not in vendor/. The defining change in this line of releases is that models, resources and login were pushed out into sibling user/admin packages. That makes the extension point your own App\Models\User, your own policies, and config values — never an edited vendor class. Anything you override in place is lost on the next composer update.

Panel-per-role. The idiomatic layout is a full admin panel plus a lighter surface (second panel, or plain Blade) for end users, sharing one auth guard. Register resources on the panel provider rather than globally so each panel can be tested in isolation.

Feature work is mostly Filament resources. Day to day you are generating resources and wiring form schemas, tables and policies:

php artisan make:filament-resource Invoice --generate

Then move the generated class into your app namespace so it is not shadowed by a kit-provided resource of the same name. Keep policy logic in policies, not in canViewAny() closures scattered across resources.

Desktop-first assumptions. On the NativePHP path, anything that assumes a live web request will bite you in the packaged build. Prefer the local disk over S3, synchronous or short-lived jobs over long-running queues, and relative asset paths over absolute URLs. Gate genuinely web-only features behind a config flag so the desktop build can disable them without a code fork.

Localisation and seeding. Use the seeder that ships with the kit to provision the admin, then add your own seeders for demo data. Keep seeders idempotent (firstOrCreate on email, not create) so re-running migrate --seed during development does not duplicate users.

Testing pattern. Livewire::test(ResourcePage::class) plus actingAs() with a factory-built user in each role. Assert authorization explicitly — in starter kits the regressions are almost always policy/role drift, not broken form components.

Gotchas and Tips

• The description and the code disagree. The README pitch ("no external dependencies — pure PHP") contradicts a kit that ships Filament 3 and NativePHP. Verify what you actually have before planning around either story; the docs in the repo are more reliable than the one-line description.
• Version lockstep with Filament. The package version mirrors the Filament version it targets (3.3.56 ↔ Filament 3.3.56). If your app pins a different Filament patch you will get subtle panel and API mismatches. Bump both in the same PR and check whether the constraint is a caret or an exact pin — an exact pin will fight any app on a different patch.
• Guzzle 7 → 8 landed in a patch release. guzzlehttp/guzzle moved from 7.15.5 to 8.1.0 under 3.3.56. Any sibling package pinning ^7.0 produces an unsatisfiable dependency graph. Run composer why guzzlehttp/guzzle before upgrading, and smoke-test any custom HTTP clients or webhook calls — Guzzle 8 changed option handling.
• PR #100 is the real breaking edge. "Use user/admin packages for models, resources and login" relocated namespaces and extension points. If you upgraded from 3.3.55, inventory every local override of the User model, login page and resource classes, then re-verify login plus one resource before shipping.
• Publish-then-diff on upgrade. Republish config to a temp directory and diff against yours. A silently added config key surfaces as a confusing null deep in a resource, not as an error at boot.
• Blank or 404ing Filament pages are usually cache, not code. Panel registration order and stale component caches account for most "it worked yesterday" reports. php artisan filament:cache-components and php artisan optimize:clear fix a surprising share.
• The frontend is pnpm with overrides. 3.3.x moved pnpm overrides into pnpm-workspace.yaml and patches shell-quote and source-map-js. If you add JS dependencies, check you are not un-patching those or reintroducing the advisory.
• Mirror the CI locally. The project standardises workflows and runs PHPStan on PHP 8.4. Run static analysis at your own level and test on the PHP version you actually deploy — static-analysis-only failures after a bump are common and cheap to catch early.
• Extension points to prefer, in order: config values, policies and gates, resource visible()/canViewAny(), events, and only then class overrides. Anything past config is a merge burden on every patch release.
• Expect noise in patch releases. The maintainer runs grouped Dependabot across Composer, npm and Actions with auto-merge for Actions minor/patch, so patch numbers routinely contain runtime dependency movement. Read patch changelogs; do not assume they are inert.