Stimulus

Installation

Stimulus is a lightweight JavaScript framework that aims to facilitate the integration of JavaScript components into a project. It connects JavaScript objects called controllers to HTML elements on a page via data-* attributes.

composer require symfony/stimulus-bundle

# remove the webpack-compatible @symfony/stimulus-bridge
npm rm @symfony/stimulus-bridge

// vite.config.js
import { defineConfig } from 'vite'
import symfonyPlugin from 'vite-plugin-symfony';

export default defineConfig({
  plugins: [
    symfonyPlugin({
      stimulus: true

      // or specify the path to your controllers.json
      // stimulus: './assets/other-dir/controllers.json'
    }),
  ],

  build: {
    rollupOptions: {
      input: {
        "app": "./assets/app.js",
      }
    }
  },
});

If you are using TypeScript. Add these type definitions for the import.meta.stimulusXXX and *?stimulus type imports in an env.d.ts file.

/// <reference types="vite-plugin-symfony/stimulus/env" />

If you ran the Flex recipe the import has probably already been added.

// assets/app.js
import './bootstrap.js';

Add the stimulus application generation routines compatible with symfony/stimulus-bundle and vite.

assets/bootstrap.js

import { startStimulusApp, registerControllers } from "vite-plugin-symfony/stimulus/helpers";

const app = startStimulusApp();
registerControllers(
  app,
  import.meta.glob('./controllers/*_controller.js', {
    query: "?stimulus",
    /**
     * always true, the `lazy` behavior is managed internally with
     * import.meta.stimulusFetch (see reference)
     */
    eager: true,
  })
)

assets/bootstrap.ts

import { registerControllers } from "vite-plugin-symfony/stimulus/helpers";

registerControllers(
  app,
  import.meta.glob<StimulusControllerInfosImport>(
    "./controllers/*_controller.ts",
    {
      query: "?stimulus",
      /**
       * always true, the `lazy` behavior is managed internally with
       * import.meta.stimulusFetch (see reference)
       */
      eager: true,
    },
  ),
);

{# base.html.twig #}

{% block stylesheets %}
  {{ vite_entry_link_tags('app') }}
{% endblock %}

{% block javascripts %}
  {{ vite_entry_script_tags('app') }}
{% endblock %}

{# in some template #}
<h1 {{ stimulus_controller('welcome') }}></h1>

// ./assets/controllers/welcome_controller.js
import { Controller } from "@hotwired/stimulus";

import.meta.stimulusFetch = "eager";
import.meta.stimulusIdentifier = "welcome";

export default class controller extends Controller {

  static targets = ["title"];
  static values = {
    name: String,
  };
  connect() {
    this.titleTarget.textContent = `hello ${this.nameValue}`;
  }
}

Examples

The development repository lhapaipai/symfony-vite-dev contains a folder playground/stimulus-basic and another playground/stimulus containing a complete implementation of Stimulus with Symfony UX.

git clone https://github.com/lhapaipai/symfony-vite-dev.git
cd symfony-vite-dev

# install vite-bundle dependencies
# build vite-plugin-symfony
make install

cd playground/stimulus-basic
# or for Symfony UX
cd playground/stimulus

composer install
symfony serve
pnpm dev