Mobilekit Laravel Package

Getting Started

MobileKit is a Laravel starter kit that pairs a Filament admin panel with a NativePHP mobile app — one codebase, two surfaces. Install it as a project skeleton rather than a library you composer require mid-project:

composer create-project jeffersongoncalves/mobilekit my-app
cd my-app && composer install && npm install   # or pnpm install
cp .env.example .env && php artisan key:generate
php artisan migrate --seed
php artisan filament:install --panels   # only if panels aren't pre-wired

Look at these first, in order:

1. composer.json — confirms the Laravel major (13 as of 3.3.56) and pulls in nativephp/mobile (4.3.0) plus the Filament version.
2. app/Providers/Filament/ — the panel provider defines resources, pages, and the login flow. As of PR #118 the user/admin models, resources, and login are supplied by separate user/admin packages, so the panel provider is where those get registered.
3. routes/ and the NativePHP entrypoint — the mobile shell boots Laravel from a bundled PHP runtime; anything you'd expect in public/index.php on web lives here for the app.
4. config/nativephp.php (published via php artisan vendor:publish) — app ID, version, and hot-reload settings.

First useful task: run php artisan serve and log into /admin, then run php artisan native:run and confirm the same data renders in the mobile shell. Getting both surfaces talking to the same Eloquent models is the whole point of the kit, and it validates your environment before you start customizing.

Implementation Patterns

Shared models, divergent UI. Keep business logic in Eloquent models and service classes; let Filament resources handle admin CRUD and Livewire/NativePHP screens handle the mobile experience. Resist putting query logic in Filament resources — you'll want it from the mobile side too.

Panel-per-audience. With the user/admin package split introduced in this release, treat admin and end-user surfaces as separate Filament panels (or separate guards) rather than one panel with role checks. Register each in its own provider and give them distinct paths, e.g. /admin and /app.

// app/Providers/Filament/AdminPanelProvider.php
->id('admin')
->path('admin')
->login()
->authGuard('web')

NativePHP as a thin shell. The mobile layer is a WebView plus a PHP runtime. Treat it as a delivery mechanism, not an architecture. Anything device-specific (camera, filesystem, push) goes through NativePHP's facades behind an interface so you can fake it in tests and fall back to browser APIs on web.

Feature flags for mobile-only code. Web and mobile ship on different cadences — the mobile binary needs a store review, the web doesn't. Gate new mobile screens behind config flags so a web deploy doesn't force an app release.

Migrations are shared, so be additive. Both surfaces read the same schema. Adding a nullable column is safe; renaming one breaks whatever binary is still in users' hands. Use expand/contract migrations when you must change shape.

Testing. Filament resources are testable with Livewire's Livewire::test() against list/create pages. For the mobile side, test the underlying HTTP/Livewire layer rather than the shell — the shell has no meaningful test surface.

Gotchas and Tips

This release is almost entirely dependency and CI churn — but PR #118 is the one to read. "Use user/admin packages for models, resources and login" moves User, the admin resources, and the login flow into external packages. If you've customized those files in place, your edits will be overwritten or orphaned on upgrade. Before bumping, diff your app/Models/User.php and any Filament resource you've touched against the new package-provided versions, and move customizations into subclasses, traits, or your own resources registered alongside.

Pin the Filament version deliberately. The headline is "Bump Filament to v3.3.56," which is a patch bump — low risk. But if you're mid-upgrade from a v2-era fork, Filament 3 changed resource/form APIs substantially. Check composer.lock for the locked Filament constraint rather than trusting the release title.

Laravel 13 is now the stated target. The composer.json description was corrected to Laravel 13, which strongly implies the constraint moved. If your project is on Laravel 12, hold the upgrade or verify the constraint allows it — a starter kit's framework constraint is not a suggestion.

NativePHP 4.3.0 may require a rebuild. The nativephp/mobile bump from 4.2.0 to 4.3.0 is a minor version. Minor bumps in NativePHP have historically meant the embedded PHP runtime or plugin bridge changed, so a fresh php artisan native:install / re-compile is usually needed. Don't just composer update and assume the existing binary still works.

pnpm-workspace.yaml now holds the overrides. PRs #122 and #124 moved pnpm overrides out of package.json and added patches for shell-quote and source-map-js. If you're on npm or yarn, the security patches those overrides carry won't apply to you — audit your own dependency tree. If you're on pnpm, don't reintroduce a pnpm.overrides block in package.json; it'll silently conflict.

Dependabot noise hides the signal. Of ~26 PRs in this release, roughly 20 are automated bumps. Skim the changelog for anything authored by a human (@jeffersongoncalves) — those are the behavioral changes. Everything else you can verify with composer outdated locally.

Debugging the mobile shell. php artisan native:debug plus the device console gets you most of the way. The common failure is a route or asset URL that resolves on web (http://localhost) but not inside the packaged app — set APP_URL explicitly and avoid hardcoded absolute URLs in Blade.

Extension points worth knowing. Publish config and views (vendor:publish --tag=nativephp-config, Filament's --tag=filament-views) rather than editing inside vendor/. Filament resource and panel providers, NativePHP facades, and the service container bindings are the intended seams — the starter kit's own classes are examples, not contracts.