Установка через npm и yarn

Stimulus — это легковесный JavaScript-фреймворк, ориентированный на управление поведением HTML-элементов с минимальными усилиями. Для его использования в современных проектах предпочтительно применять менеджеры пакетов, такие как npm или yarn, что обеспечивает удобство интеграции и управление зависимостями.

Установка через npm

Для установки Stimulus через npm необходимо выполнить команду:

npm install @hotwired/stimulus

После успешной установки в проекте появится папка node_modules/@hotwired/stimulus, а также запись о зависимости в package.json:

"dependencies": {
  "@hotwired/stimulus": "^3.3.0"
}

Stimulus готов к импорту в модульном JavaScript-коде:

import { Application } from "@hotwired/stimulus";

Создание экземпляра приложения выполняется следующим образом:

const application = Application.start();

На этом этапе приложение Stimulus готово к подключению контроллеров.

Установка через yarn

Для установки через yarn используется аналогичная команда:

yarn add @hotwired/stimulus

Эта команда добавляет Stimulus в зависимости проекта и обеспечивает синхронизацию с yarn.lock. Импорт и инициализация идентичны npm-версии:

import { Application } from "@hotwired/stimulus";

const application = Application.start();

Структура проекта после установки

После установки Stimulus структура проекта обычно включает:

project/
├─ node_modules/
│  └─ @hotwired/stimulus/
├─ src/
│  ├─ controllers/
│  └─ index.js
├─ package.json
└─ yarn.lock / package-lock.json
  • controllers/ — каталог для размещения контроллеров Stimulus.
  • index.js — основной файл, в котором инициализируется приложение.

Инициализация контроллеров

После старта приложения можно регистрировать контроллеры. Предположим, есть контроллер hello_controller.js:

// src/controllers/hello_controller.js
import { Controller } from "@hotwired/stimulus";

export default class extends Controller {
  static targets = ["name"];

  greet() {
    console.log(`Hello, ${this.nameTarget.value}!`);
  }
}

Регистрация контроллера в основном файле:

import { Application } from "@hotwired/stimulus";
import HelloController from "./controllers/hello_controller";

const application = Application.start();
application.register("hello", HelloController);

В HTML:

<div data-controller="hello">
  <input data-hello-target="name" type="text" value="Stimulus">
  <button data-action="click->hello#greet">Greet</button>
</div>

Особенности работы с npm и yarn

  • npm чаще используется в проектах с Node.js и Webpack.
  • yarn обеспечивает более быструю установку и детерминированные зависимости.
  • Stimulus не зависит от конкретного сборщика, поэтому может использоваться с Webpack, Vite, Rollup и другими инструментами.

Автоматическая регистрация контроллеров

Для упрощения разработки можно использовать динамическую загрузку всех контроллеров:

import { Application } from "@hotwired/stimulus";
const application = Application.start();

const context = require.context("./controllers", true, /\.js$/);
context.keys().forEach((filename) => {
  const controller = context(filename).default;
  const name = filename.replace(/^.\//, "").replace(/_controller\.js$/, "");
  application.register(name, controller);
});

Этот подход позволяет добавлять новые контроллеры без ручной регистрации.

Советы по обновлению Stimulus

  • Проверять совместимость версии с текущим сборщиком.
  • Использовать npm update @hotwired/stimulus или yarn upgrade @hotwired/stimulus для обновления.
  • Контролировать версию в package.json с помощью точных или диапазонных номеров (^, ~) для стабильности проекта.
Оглавление