Download the PHP package hotwired/stimulus-laravel without Composer

Introduction

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!

Inspiration

This package was inspired by the stimulus-rails gem.

Installation Steps

Stimulus Laravel may be installed via composer:

Next, if you're on a fresh Laravel app (see the #manual-installation if you're not), you may run install command:

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.

Making a New Controller

To make a new Stimulus controller, run:

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:

Regenerate the Manifest

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:

Manual Installation

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 Vite steps.

1. Either way, you need to install the lib via composer first:

Importmap Steps

2. Create resources/js/controllers/index.js and load your controllers like this:

3. Create a resources/js/libs/stimulus.js with the following content:

4. Create a resources/js/libs/index.js file with the following content (or add it to an existing file if you have one):

5. Add the following line to your resources/js/app.js file:

6. Publish the vendor dependencies:

7. Pin the Stimulus dependency:

8. Finally, pin the stimulus-loading dependency on your routes/importmap.php file:

Vite Steps

1. Create a resources/js/controllers/index.js and chose if you want to register your controllers manually or not:

   Register controllers manually

   Register controllers automatically

   If you prefer to automatially register your controllers you can use the stimulus-vite-helpers NPM package.

   And install the NPM package:

2. Create resources/js/libs/stimulus.js with the following content:

3. Create a resources/js/libs/index.js file (if it doesn't exist) and add the following line to it:

4. Add the following line to your resources/js/app.js file:

5. Finally, add the Stimulus package to NPM:

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Drop me an email at [email protected] if you want to report security vulnerabilities.

License

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

Credits

• Tony Messias
• All Contributors