Download the PHP package emaia/laravel-hotwire without Composer

Laravel Hotwire

The complete Hotwire stack for Laravel — Turbo Drive, Turbo Streams, Stimulus controllers, and Blade components out of the box.

Table of Contents

• Requirements
• Installation
  • Quick Start
  • Explore the Docs
• Turbo
• Stimulus Controllers
  • Top-level controllers
  • Turbo
  • Optimistic
  • Dev
  • Publish Controllers
• Stimulus Attribute Helpers
• Blade Components
• Verify Your Setup
• Configuration
• View Customization
• Extending
• Testing
• Manual Installation
• Changelog
• Contributing
• Security Vulnerabilities
• Credits
• License

Requirements

• PHP 8.3+
• Laravel 12+
• Stimulus with a loader compatible with import.meta.glob ( e.g. @emaia/stimulus-dynamic-loader)
• Tailwind CSS
• Vite.js

Installation

Publish the configuration file (optional):

Quick Start

The installation command scaffolds the Hotwire setup in your Laravel application — JS entry points, Stimulus loader, Turbo imports, and CSS custom variants:

This will:

1. Copy JS and CSS scaffolding to resources/
2. Add @hotwired/stimulus, @hotwired/turbo and @emaia/stimulus-dynamic-loader to your package.json
3. Show instructions for the next steps

Only the three core dependencies above are added at installation time. Extra npm packages required by specific components (e.g. tippy.js, @emaia/sonner) are published on demand by hotwire:check once you actually use a component that depends on them.

Options:

If a target file already exists and is identical, it is skipped. If it differs, the command asks for confirmation before overwriting (unless --force is used).

After installation, a good next step is:

1. Browse the package docs in the terminal to see what is available
2. Publish the Stimulus controllers you actually want to use
3. Run hotwire:check to verify controllers and npm dependencies used by your views

Explore the Docs

You can browse the package docs directly in the terminal:

Turbo

This package includes emaia/laravel-hotwire-turbo as a dependency, providing full Turbo integration for Laravel:

• Turbo Streams — fluent builder for append, prepend, replace, update, remove, morph, refresh, and more
• Turbo Frames — <x-turbo::frame> Blade component with lazy loading support
• DOM helpers — dom_id() and dom_class() for consistent element identification
• Request detection — wantsTurboStream() and wasFromTurboFrame() macros
• Blade directives — @turboNocache, @turboRefreshMethod('morph'), etc.
• Testing utilities — InteractsWithTurbo trait with assertTurboStream() assertions

See the full documentation at emaia/laravel-hotwire-turbo.

Stimulus Controllers (standalone)

Stimulus controllers without an associated Blade component. Used directly via data-controller and data-action.

Controllers live flat at the top level (resources/js/controllers/<name>_controller.{js,ts}). Substrate folders (turbo/, optimistic/, dev/) group controllers tied to a specific technical layer and use Stimulus' -- separator in the identifier.

Top-level controllers

Turbo

Controllers tied to Turbo Drive / Turbo Frames.

Optimistic

Dev

Publish Stimulus Controllers

Publish the controllers you want to use in your app so they can be discovered by the bundler (Vite).

Interactive — select which controllers to publish:

By name — publish a specific controller:

Substrate namespace — publish every controller under a substrate folder (turbo, optimistic, dev):

Multiple arguments — mix names and substrate namespaces:

All at once:

List available controllers (with publication status):

Update only controllers that are already published but differ from the package source:

--outdated never installs controllers that haven't been published yet, and skips those that are already up to date.

Overwrite existing files:

Top-level controllers are copied flat to resources/js/controllers/ (e.g. modal → resources/js/controllers/modal_controller.js, identifier modal). Controllers under a substrate folder preserve that folder and use Stimulus' -- separator (e.g. turbo/progress → resources/js/controllers/turbo/progress_controller.js, identifier turbo--progress). @emaia/stimulus-dynamic-loader discovers and loads them automatically via import.meta.glob.

If a controller already exists and is identical to the package version, the command reports it as up to date. If it differs, it asks for confirmation before overwriting.

Name collisions: package controller names are effectively reserved in resources/js/controllers/. If you write your own controller whose file name matches a package one (e.g. your own tabs_controller.js), the tooling treats it as an outdated copy of the package controller — hotwire:controllers --force (or --outdated --force) and hotwire:check --fix will overwrite it without prompting. Before naming a new controller, check the taken names with php artisan hotwire:controllers --list and pick a different one.

Stimulus Attribute Helpers

Build Stimulus data-* attributes from Blade without hand-writing the verbose markup. The primary stimulus() entry point returns a fluent, chainable builder that is Htmlable (renders directly in {{ }}) and Arrayable (merges into a component's attribute bag):

stimulus_controller() is an alias for stimulus()->controller(...); stimulus_action() and stimulus_target() are shortcuts for stimulus()->action(...) and stimulus()->target(...).

See Stimulus attribute helpers for values/classes/outlets, action params, stacking multiple controllers, attribute-bag merging and the escaping rules.

Blade Components

Verify Your Setup

List components and their required controllers:

Shows each Blade component, its tag, and the Stimulus controllers it depends on — with publication status for each.

Check controllers used in your views (components and direct usage):

Scans resources/views for Hotwire components and direct Stimulus controller usage — data-controller attributes and the stimulus_controller() / stimulus()->controller() / ->controllers() / stimulus_action() / stimulus_target() helpers — then verifies two things:

1. Stimulus controllers — every controller required by a used component, or referenced directly, is published and up to date.
2. npm dependencies — every external package imported by those controllers (e.g. @emaia/sonner, tippy.js) is declared in your package.json (dependencies or devDependencies).

Exits with code 1 if either has pending items (useful for CI).

Both the configured prefix (hwc by default) and the literal hotwire alias are recognized, so views like <x-hwc::flash-message /> and <x-hotwire::flash-message /> are detected equally. Only controllers shipped by the package are checked — your own controllers are ignored — and Blade comments and <script>/<style> blocks are stripped first, so commented-out code is skipped.

Example output:

In interactive mode, hotwire:check asks whether to run the detected package manager install command after adding dependencies. In non-interactive scripts, use --fix --install to run it automatically.

Configuration

Change prefix to use a different prefix for Blade components. E.g. 'prefix' => 'hotwire' → <x-hotwire::modal>.

View Customization

To customize the HTML/Tailwind of the components:

Views published to resources/views/vendor/hotwire/ will take precedence over the package defaults.

Extending the package

Laravel Hotwire uses a single registry as the source of truth for:

• Blade components
• Stimulus controllers
• external npm dependencies
• docs paths
• public categories

When adding a new component or controller to this package, update the registry entry in src/Registry/catalog.php.

Example component entry:

Example controller entry:

More details: docs/registry.md

Testing

Manual Installation

If you prefer to set things up manually instead of using hotwire:install, follow the steps below.

Project setup (using Vite)

Install the required js dependencies:

TailwindCSS (v4)

Add these settings to your CSS entrypoint resources/css/app.css:

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Contributions are welcome via pull requests.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Ednilson Maia
• All Contributors

License

The MIT License (MIT). Please see License File for more information.