Laravel React Starter Kit Laravel Package

Getting Started

This is a starter kit rather than a library, so "getting started" means scaffolding a new app and orienting yourself in the generated codebase.

1. Scaffold: laravel new my-app --using=scajal/laravel-react-starter-kit. This pulls the kit, installs Composer/NPM dependencies, and runs the usual setup. If the installer path fails, clone the repo and run composer install && npm install && npm run build.
2. Configure WorkOS AuthKit — this is the first thing that will block you. Add WORKOS_CLIENT_ID, WORKOS_API_KEY, and the redirect URL to .env. Sign-in is entirely delegated to WorkOS, so you cannot log in locally until these are set and the redirect URI matches your WorkOS dashboard.
3. Migrate and seed: php artisan migrate --seed. You need at least one user + team to see the app meaningfully.
4. Look here first:
   • app/Data/ — the laravel-data DTOs that drive Inertia props.
   • resources/js/pages/ — the React pages.
   • app/Filament/ — admin resources for users/teams/members.
   • lang/ and resources/js/lang/ (or equivalent) — the paired Laravel/React translation files.
5. First use case: sign in, create a team, invite a member, switch teams via the switcher, then open /administration as an Owner/Administrator to confirm the Filament panel and audit timeline work.

Implementation Patterns

Adding a page with typed props. Define a laravel-data class in app/Data/, return it from your controller alongside Inertia::render, and regenerate the TypeScript types (the kit includes generated TS types and a drift test). Reference the generated type in your React page rather than hand-writing an interface — this is the intended workflow.

Type-safe routes. Use Wayfinder-generated helpers in React instead of string URLs. When you add or rename a route, regenerate the Wayfinder artifacts as part of your build step so the frontend doesn't reference stale routes.

Teams and roles. Access is role-based (Owner, Administrator, Member) with memberships and a current-team concept. Day to day you'll:

• Scope queries to the current team — never rely on a bare Model::all().
• Gate actions with policies that check the user's role on the current team, not a global role.
• Use the switcher's current-team resolution as the single source of truth when writing new team-scoped features.

Filament admin. Add new resources under the Filament panel namespace for anything admins should manage. Reuse the existing user/team/member resources as templates for form/table conventions, and confirm panel authorization (who can reach /administration) matches your role model before exposing new resources.

Audit trail. The kit records changes to users, teams, memberships, and preferences and renders them as a timeline. If you add a model that should be audited, follow the existing model-event/logging pattern rather than inventing a parallel system, so entries appear in the same timeline.

Localization. Translations are shared between Laravel and React. When adding a key, add it to both sides in the same change. Store locale on the user account (as the kit already does) so it persists across sessions.

Theming. Light/dark/system is stored per user; use the existing appearance mechanism instead of introducing a separate theme toggle, so preferences stay on the account.

SSR and React Compiler. Keep components SSR-safe (no window/document at module or render top-level; guard browser-only logic in effects). The React Compiler is enabled, so prefer straightforward component code and let it memoize — avoid fighting it with manual memoization that duplicates its work.

Gotchas and Tips

• The type drift test is your friend and your enemy. It fails whenever DTOs and generated TS types diverge. Run the type-generation step after any DTO change; if a test fails in CI, regenerate rather than hand-editing the generated file.
• WorkOS lockout. Inactive users are signed out automatically, and sign-in is fully external. If you can't log in, check .env WorkOS values and the redirect URI before debugging app code. Local/staging needs its own WorkOS environment or shared credentials.
• Team scoping leaks. The current-team switcher makes it easy to forget scoping. Every new team-aware query and policy must explicitly resolve the current team — a missing scope is a data-leak bug, not just a UX bug.
• Filament panel exposure. /administration is a real surface. Verify the panel's access gate against the role model; don't assume the route prefix hides it.
• Translation drift. Two files must stay in sync; a missing React key shows raw keys in the UI. Add a checklist step or a test that asserts key parity between Laravel and React translation files.
• Wayfinder regeneration. Stale route helpers cause runtime errors after route changes. Wire regeneration into dev/build (watch mode if available) so you're not chasing phantom 404s.
• SSR build failures. Browser-only code crashes the SSR render, not the client. If a page 500s only on first load, check for top-level window/localStorage access.
• React Compiler surprises. Non-idiomatic patterns (mutating props, conditional hooks, refs read during render) may surface as warnings or miscompiles. Prefer plain, rule-compliant components.
• v0.1.0 maturity. This is an initial release; expect rough edges and API churn. Pin the version, and keep your customizations in clearly separated files/commits so upstream changes are easy to reconcile. Check the repo for upgrade notes before bumping.
• Extension points to lean on: laravel-data DTOs (props), Filament resources (admin), the audit logging pattern (history), and the shared translation structure (i18n) — extend through these rather than bypassing them, or you'll lose the kit's type safety and consistency guarantees.