README

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:

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.

Making a New Controller

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() {
    }
}

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:

php artisan stimulus:manifest

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 Importmap Steps, otherwise follow the Vite steps.

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

composer require hotwired-laravel/stimulus-laravel

Importmap Steps

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 your routes/importmap.php file:

Importmap::pin("@hotwired/stimulus-loading", to: "vendor/stimulus-laravel/stimulus-loading.js", preload: true);

Vite Steps

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

Register controllers manually

// 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)

Register controllers automatically

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

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 tonysm@hey.com if you want to report security vulnerabilities.

License

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

hotwired-laravel / stimulus-laravel

Maintainers

Details