Stimulus is a JavaScript framework with modest ambitions. It doesn’t seek to take over your entire front-end in fact, it’s not concerned with rendering HTML at all. Instead, it’s designed to augment your HTML with just enough behavior to make it shine. Stimulus pairs beautifully with Turbo to provide a complete solution for fast, compelling applications with a minimal amount of effort. Together they form the core of Hotwire.
Stimulus for Laravel makes it easy to use this modest framework with both import-mapped and JavaScript-bundled apps. It relies on either Importmap Laravel to make Stimulus available via ESM or a Node-capable Laravel using Vite to include Stimulus in the bundle. Make sure to install one of these first!
This package was inspired by the stimulus-rails gem.
Stimulus Laravel may be installed via composer:
composer require hotwired-laravel/stimulus-laravel
Next, if you're on a fresh Laravel app (see the #manual-installation if you're not), you may run install command:
php artisan stimulus:install
That's it. The install command will automatically detect if you're using Importmap Laravel or Vite to manage your JavaScript dependencies. If you're using Importmap Laravel, we're pinning the Stimulus dependency and publishing a local dependency to your public/vendor
folder and pinning it so you don't have to register Stimulus controllers. If you're using Vite, we'll add the Stimulus dependecy to your package.json
.
The install command generates a resources/js/libs/stimulus.js
file that installs Stimulus. It also creates your first Stimulus controller at resources/js/libs/controllers/hello_controller.js
. It will also create a resources/js/libs/index.js
that ensures the resources/js/controllers/index.js
module is imported.
When using Importmap Laravel, the resources/js/controllers/index.js
will use the published stimulus-loading
dependency to either eager load or lazy load your Stimulus controller registrations automatically, so you don't have to manually register them. When using Vite, that file will be auto-generated whenever you make a new Stimulus controller or whenever you run the php artisan stimulus:manifest
manually.
To make a new Stimulus controller, run:
php artisan stimulus:make hello_controller
This should create the file for you using a scaffolding to get the controller ready for you. When using Vite, it will also regenerate the resources/js/controllers/index.js
file to register your newly created Stimulus controller automatically.
There's also a hint comment on how you may use the controller in the DOM, something like this:
import { Controller } from "@hotwired/stimulus"
// Connects to data-controller="hello"
export default class extends Controller {
connect() {
}
}
The stimulus:make
command will regenerate the resources/js/controllers/index.js
file for you, registering all your controllers. If you want to manually trigger a regeneration, you may run:
php artisan stimulus:manifest
If you're installing the package on an pre-existing Laravel app, it may be useful to manually install it step by step.
If you're using Importmap Laravel, follow the Importmap Steps, otherwise follow the Vite steps.
- Either way, you need to install the lib via composer first:
composer require hotwired-laravel/stimulus-laravel
- Create
resources/js/controllers/index.js
and load your controllers like this:
import { Stimulus } from 'libs/stimulus'
// Eager load all controllers defined in the import map under controllers/**/*_controller
import { eagerLoadControllersFrom } from '@hotwired/stimulus-loading'
eagerLoadControllersFrom('controllers', Stimulus)
- Create a
resources/js/libs/stimulus.js
with the following content:
import { Application } from '@hotwired/stimulus'
const Stimulus = Application.start()
// Configure Stimulus development experience
Stimulus.debug = false
window.Stimulus = Stimulus
export { Stimulus }
- Create a
resources/js/libs/index.js
file with the following content (or add it to an existing file if you have one):
import 'controllers'
- Add the following line to your
resources/js/app.js
file:
import 'libs'
- Publish the vendor dependencies:
php artisan vendor:publish --tag=stimulus-laravel-assets
- Pin the Stimulus dependency:
php artisan importmap:pin @hotwired/stimulus
- Finally, pin the
stimulus-loading
dependency on yourroutes/importmap.php
file:
Importmap::pin("@hotwired/stimulus-loading", to: "vendor/stimulus-laravel/stimulus-loading.js", preload: true);
-
Create a
resources/js/controllers/index.js
and chose if you want to register your controllers manually or not:// This file is auto-generated by `php artisan stimulus:install` // Run that command whenever you add a new controller or create them with // `php artisan stimulus:make controllerName` import { Stimulus } from '../libs/stimulus' import HelloController from './hello_controller' Stimulus.register('hello', HelloController)
If you prefer to automatially register your controllers you can use the
stimulus-vite-helpers
NPM package.// resources/js/controllers/index.js import { Stimulus } from '../libs/stimulus' import { registerControllers } from 'stimulus-vite-helpers' const controllers = import.meta.glob('./**/*_controller.js', { eager: true }) registerControllers(Stimulus, controllers)
And install the NPM package:
npm install stimulus-vite-helpers
-
Create
resources/js/libs/stimulus.js
with the following content:
import { Application } from '@hotwired/stimulus'
const Stimulus = Application.start()
// Configure Stimulus development experience
Stimulus.debug = false
window.Stimulus = Stimulus
export { Stimulus }
- Create a
resources/js/libs/index.js
file (if it doesn't exist) and add the following line to it:
import '../controllers'
- Add the following line to your
resources/js/app.js
file:
import './libs';
- Finally, add the Stimulus package to NPM:
npm install @hotwired/stimulus
Please see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
Drop me an email at tonysm@hey.com if you want to report security vulnerabilities.
The MIT License (MIT). Please see License File for more information.