Laravel Splade Jetstream Laravel Package

Getting Started

Treat protonemedia/laravel-splade-jetstream as a legacy Jetstream scaffold for a Splade + Blade + Tailwind stack, not as a default choice for a new Laravel application. Release 1.1.1 is a narrow compatibility update: it explicitly requires Laravel 10 for new projects because the Laravel skeleton has moved to JS modules. Do not read this as Laravel 11/12 support.

Minimal path:

1. Start from a fresh Laravel 10 app that matches the package’s composer.json constraints. The 1.1.1 release notes specifically call for Laravel 10 for new projects; do not start from a newer Laravel skeleton and assume compatibility.
2. Require the package:

   composer require protonemedia/laravel-splade-jetstream
   

3. Run the Jetstream stack installer exposed by the package. In practice this is typically:

   php artisan jetstream:install splade
   

   Confirm the exact command from the README and php artisan list; if the command is absent, inspect the package service provider and installer registration.
4. Run migrations and build assets:

   php artisan migrate
   npm install
   npm run build
   

5. Register a user and exercise the dashboard, profile, password, and team screens.

Where to look first:

• The package README and composer.json for Laravel/Jetstream/Splade/Tailwind version constraints, especially the Laravel 10 expectation introduced by 1.1.1.
• app/Actions/Jetstream for profile, password, team, and token behavior.
• resources/views for the generated auth/profile/team/API screens.
• resources/js/app.js, vite.config.js, and tailwind.config.js for the frontend pipeline.
• config/jetstream.php for teams, profile photos, API tokens, and account deletion features.
• routes/web.php and php artisan route:list for Jetstream’s named routes and middleware.

First useful use case: customize the generated Jetstream profile page and team management screens with Splade components while leaving Jetstream’s backend actions and authorization intact.

Implementation Patterns

Use Splade as the presentation/interaction layer and keep Jetstream’s backend actions as the source of truth.

• Profile and password forms: bind Splade forms to existing Jetstream routes and actions.

  <x-splade-form :action="route('profile.update')" :default="$user" method="put">
      <x-splade-input name="name" label="Name" />
      <x-splade-input name="email" type="email" label="Email" />
      <x-splade-submit label="Save" />
  </x-splade-form>
  

  Leave validation, password hashing, email verification resets, and action classes in app/Actions/Jetstream unchanged unless you have a specific requirement.

• Team flows: reuse Jetstream’s membership, invitation, role, and current-team logic. In views, branch on Jetstream::hasTeamFeatures() and resolve the active team through Jetstream’s current-team conventions rather than inventing parallel membership checks.

• API tokens: keep Jetstream’s token creation/deletion actions and render the token list with Splade tables/modals. Treat token permissions and plaintext-token display as security-sensitive.

• Modal CRUD: use <x-splade-modal> for create/edit flows and return redirects or Splade events to close the modal after success. Keep controllers returning normal Laravel redirects/validation responses so Splade can intercept them.

• SPA-style navigation: use <x-splade-link> and Splade form components for partial reloads. Plain <a> and <form> tags still work as normal full-page requests, but they bypass the Splade experience.

• Flash and feedback: use Splade’s toast/flash helpers for success messages after Jetstream actions. Keep authorization failures and validation errors in Laravel’s normal response flow.

• Custom pages: add standard Laravel routes/controllers/Blade views and compose them from Splade components. You usually do not need to modify the package itself.

• Asset integration: verify the layout includes the Splade/Vite directives required by the installed Splade version, and that Tailwind scans the generated Blade views. Run npm run dev during customization and npm run build before deployment.

• Feature flags: gate UI with config/jetstream.php and Jetstream::hasApiFeatures(), Jetstream::hasTeamFeatures(), etc., so disabled features do not leave dead routes or navigation links.

Gotchas and Tips

• Laravel 10 constraint is the immediate compatibility risk: release 1.1.1 requires Laravel 10 for new projects because the Laravel skeleton moved to JS modules. Do not assume Laravel 11/12 support, and do not mix a newer Laravel skeleton with this scaffold without testing the full install.

• Legacy scaffold with narrow maintenance: 1.1.1 is a compatibility-oriented release, not a broad modernization. Pin exact versions, commit the lockfile, and test any Laravel/PHP/Node upgrade. Do not assume security patches or compatibility with current Laravel.

• Destructive scaffolding: Jetstream installers overwrite/add application files. Run only on a fresh app or after a clean commit. Never run the installer casually on an existing production codebase.

• Do not mix stacks: choose Splade, not Livewire or Inertia, for this Jetstream scaffold. Mixing stack assets, layouts, and route assumptions causes subtle breakage.

• Version matrix is the main risk: Laravel 10, Jetstream, Splade, Tailwind, and Vite versions are tightly coupled in this legacy preset. If Composer resolves oddly, inspect the package constraints before debugging application code.

• Missing Splade JavaScript: if forms submit as full page reloads or modals/links do not behave interactively, check resources/js/app.js, the Vite entry, the layout directives, and the browser console/network tab.

• CSRF and method spoofing: use Splade form components rather than hand-written forms when you expect SPA behavior. Laravel still needs CSRF tokens and _method handling for PUT/PATCH/DELETE.

• Validation and redirects: keep controllers returning Laravel validation errors and redirects. For modal forms, verify the modal closes on success and displays errors on failure; otherwise users see stale UI.

• Teams and profile photos: run php artisan storage:link and verify filesystem/disk configuration if avatar or team features are enabled. Check config/jetstream.php before assuming a feature is active.

• Route/middleware surprises: use php artisan route:list to confirm Jetstream route names and middleware such as auth:sanctum, verified, and password.confirm. Custom links should target named routes, not hard-coded URLs.

• Cache clearing: after changing config, views, or published package files, run:

  php artisan optimize:clear
  

  Then rebuild assets if Tailwind classes or Vue components changed.

• Debugging approach: inspect browser network requests for Splade requests, check storage/logs/laravel.log, run npm run dev with console open, and publish/inspect package views rather than editing vendor/.

• Extension points: prefer publishing/overriding views, using Jetstream action classes, and composing Splade components. Avoid patching vendor code; it will be lost on the next Composer install and is especially risky for a legacy package.

• Security review: because this scaffold is dated, review auth flows, password confirmation, two-factor, API token display, and team authorization before relying on it in any real application. For new work, prefer a maintained Laravel starter kit or current Splade/Jetstream setup instead.