Настройка с Webpack и другими сборщиками

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

Подключение Stimulus через npm

Первым шагом является установка Stimulus как зависимости проекта:

npm install @hotwired/stimulus

После установки пакет становится доступным для импорта в JavaScript-файлах проекта. Для проектов с Webpack обычно создают файл index.js или application.js, где инициализируется Stimulus:

import { Application } from "@hotwired/stimulus";
import { definitionsFromContext } from "@hotwired/stimulus-webpack-helpers";

const application = Application.start();
const context = require.context("./controllers", true, /\.js$/);
application.load(definitionsFromContext(context));

Здесь используется require.context для автоматического подключения всех контроллеров, расположенных в папке controllers.

Структура контроллеров

Контроллеры Stimulus организуются в отдельной директории, обычно controllers. Каждому контроллеру соответствует отдельный файл, имя которого совпадает с именем контроллера:

controllers/
├── hello_controller.js
├── modal_controller.js
└── tabs_controller.js

Пример базового контроллера:

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

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

  connect() {
    this.outputTarget.textContent = "Stimulus контроллер подключен!";
  }

  greet() {
    alert("Привет от Stimulus!");
  }
}

Ключевые моменты:

  • static targets — декларация элементов DOM, на которые контроллер будет ссылаться.
  • connect() — метод, вызываемый при подключении контроллера к DOM.
  • Методы контроллера могут быть привязаны к событиям через data-action.

Настройка Webpack

Для проектов на Webpack важно правильно настроить обработку JavaScript и папки с контроллерами. Стандартный webpack.config.js может выглядеть так:

const path = require('path');

module.exports = {
  entry: './app/javascript/application.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'public/packs'),
  },
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: ['@babel/preset-env']
          }
        }
      }
    ]
  },
  resolve: {
    extensions: ['.js']
  }
};

Особенности:

  • Использование babel-loader обеспечивает совместимость с современным JavaScript.
  • Автоматическая загрузка контроллеров через require.context позволяет динамически подгружать новые файлы без изменений в конфигурации Webpack.
  • Папка public/packs может быть интегрирована в шаблоны HTML или Rails-приложения.

Настройка Vite и других сборщиков

Stimulus также легко интегрируется с Vite. Для этого создают файл main.js:

import { Application } from "@hotwired/stimulus";
import { definitionsFromContext } from "@hotwired/stimulus-webpack-helpers";

const application = Application.start();
const context = import.meta.glob("./controllers/**/*.js", { eager: true });
Object.values(context).forEach(module => application.load(module));

Отличия от Webpack:

  • Вместо require.context используется import.meta.glob, поддерживаемый Vite и современными сборщиками.
  • Опция { eager: true } позволяет сразу загрузить все модули.

Работа с пакетными менеджерами и CDN

Stimulus может подключаться не только через npm, но и через CDN:

<script src="https://unpkg.com/@hotwired/stimulus/dist/stimulus.umd.js"></script>
<script>
  const application = Stimulus.Application.start();
</script>

Такой подход удобен для небольших проектов, где нет необходимости в сборке модулей, но требует явного подключения всех контроллеров через <script> или import.

Советы по организации сборки

  1. Автозагрузка контроллеров — сокращает время на подключение новых модулей.
  2. Разделение логики по контроллерам — улучшает поддержку кода и читаемость.
  3. Использование современных сборщиков — обеспечивает совместимость с последними стандартами JavaScript.
  4. Минимизация bundle — важно при больших проектах для ускорения загрузки страниц.
  5. Интеграция с CSS и другими ассетами — Stimulus не диктует работу с стилями, но Webpack и Vite позволяют импортировать CSS в том же месте, что и контроллеры.

Примеры взаимодействия сборки с Rails

В Rails-проектах Stimulus интегрируется через Webpacker или jsbundling-rails. Стандартная структура:

app/javascript/controllers/
app/javascript/application.js

Инициализация в application.js выглядит аналогично:

import { Application } from "@hotwired/stimulus";
import { definitionsFromContext } from "@hotwired/stimulus-webpack-helpers";

const application = Application.start();
const context = require.context("./controllers", true, /\.js$/);
application.load(definitionsFromContext(context));

Rails автоматически компилирует ассеты и подключает bundle.js в шаблонах через javascript_pack_tag.

Stimulus с современными сборщиками обеспечивает чистую архитектуру контроллеров, быструю загрузку и простую поддержку динамической логики интерфейса. Правильная настройка Webpack, Vite или аналогичных инструментов является ключевым моментом в организации масштабируемого проекта.

Оглавление