Symfony: Webpack Encore — плагин для управления ресурсами

Позавчера обнаружил новость ^[1] о том, что команда Symfony выпустила плагин Webpack Encore для интеграции замечательного инструмента Webpack ^[2] в ваше приложение. Если вы не знакомы с Webpack, то я настоятельно рекомендую ознакомиться с ним, так как он возможно решит множество вопросов связанных с управлением ресурсами в вашем проекте. В любом случае даже если вы не собираетесь его использовать, знать о том что он существует будет крайне полезным. Очень хорошо этот инструмент описан тут ^[3].

Вступление

В свое время я опробовал множество разных подходов и инструментов для управления ресурсами. Как правило для каждого проекта приходилось выбирать, в зависимости от сложности структуры, разные решения. Но какое решение я бы не выбрал у меня всегда оставалось ощущение некоторой неудовлетворенности. Всегда оставался либо какой-то костыль, либо приходилось подстраиваться под решение.

Два дня назад я попробовал плагин для Symfony проекта Webpack Encore. Всего два дня и возможно через некоторое время я изменю свое мнение по поводу этого плагина, но сейчас находясь под впечатлением я хочу показать вам те возможности, которые он предлагает.

Необходимые инструменты

Вам потребуется какой-либо тестовый проект на Symfony >= 3.3, NodeJS ^[4] и менеджер пакетов Yarn ^[5]. Вы можете использовать Npm, но в данном посте примеры будут с использованием Yarn.

Для теста мы будем подключать к проекту FontAwesome, Jquery, Bootstrap и какие-то свои выдуманные ресурсы.

Установка

Сначала установим плагин Webpack Encore. В корне приложения:

yarn add @symfony/webpack-encore --dev

Мы будем использовать SASS, поэтому добавим пару пакетов:

yarn add sass-loader node-sass --dev

Не забудьте добавить в .gitignore каталог node_modules.

Подготовка ресурсов

Я создам в корне приложения каталог assets/ куда положу все необходимые ресурсы. В результате мой каталог будет выглядеть так:

+-assets/
---+ dist/
------+ fontawesome/
------+ jquery/
------+ bootstrap/

Дополнительно я создам в корне assets/ файл app.scss, который будет главным файлом ресурсов. Вовсе не обязательно иметь каталог dist с библиотеками, их можно установить с помощью Yarn. Я выбрал такой путь для большей наглядности.

Теперь необходимо создать инструкции для плагина. Для этого в корне приложения создадим файл webpack.config.js со следующим содержимым:

/* подключим плагин */
var Encore = require('@symfony/webpack-encore');

Encore
   /* Установим путь куда будет осуществляться сборка */
   .setOutputPath('web/build/')
   /* Укажем web путь до каталога web/build */
   .setPublicPath('/build')
   /* Каждый раз перед сборкой будем очищать каталог /build */
   .cleanupOutputBeforeBuild()
   /* Добавим наш главный файл ресурсов в сборку */
   .addStyleEntry('styles', './assets/app.scss')
   /* Включим поддержку sass/scss файлов */
   .enableSassLoader()
   /* В режиме разработки будем генерировать карту ресурсов */
   .enableSourceMaps(!Encore.isProduction());

/* Экспортируем финальную конфигурацию */
module.exports = Encore.getWebpackConfig();

Теперь можно заняться ресурсами. Отредактируем наш файл app.scss:

@import "dist/fontawesome/css/font-awesome";
@import "dist/bootstrap/css/bootstrap";
/* Тут можно определить свои стили или подключить собственные библиотеки */

Запускаем билд. В корне приложения:

./node_modules/.bin/encore dev

Если все прошло гладко, вы увидите в каталоге web/build файл styles.css, а так же папку fonts, куда скопированы все шрифты font-awesome на которые ссылается font-awesome.css. Если вы прописали какие-то свои стили, которые используют изображения, то эти изображения так же подтянутся в папку web/build/images. В результирующих файлах стилей все пути соответственно будут переписаны.

Благодаря сгенерированным картам ресурсов, мы можем комфортно использовать отладчик в браузере. Помимо стилей, в каталоге web/builds появится файл manifest.json, о нем чуть позже.

Сейчас необходимо подключить JavaScript, который нам необходим. Для этого добавим в каталог assets/ файл app.js со следующим содержимым:

var $ = require('./dist/jquery/jquery-3.2.1');
require('./dist/bootstrap/js/bootstrap');

Теперь отредактируем немного наш файл webpack.config.js:

/* подключим плагин */
var Encore = require('@symfony/webpack-encore');

Encore
   /* Установим путь куда будет осуществляться сборка */
   .setOutputPath('web/build/')
   /* Укажем web путь до каталога web/build */
   .setPublicPath('/build')
   /* Каждый раз перед сборкой будем очищать каталог /build */
   .cleanupOutputBeforeBuild()

   /* --- Добавим основной JavaScript в сборку --- */
   .addEntry('scripts', './assets/app.js')

   /* Добавим наш главный файл ресурсов в сборку */
   .addStyleEntry('styles', './assets/app.scss')
   /* Включим поддержку sass/scss файлов */
   .enableSassLoader()
   /* В режиме разработки будем генерировать карту ресурсов */
   .enableSourceMaps(!Encore.isProduction());

/* Экспортируем финальную конфигурацию */
module.exports = Encore.getWebpackConfig();

Теперь перезапустим сборку:

./node_modules/.bin/encore dev

Если все прошло гладко, вы получите файл scripts.js в каталоге web/builds.
У вас может возникнуть проблема со скриптами, которые ожидают, что JQuery будет доступен глобально. Когда вы делаете var $ = require(some.js), то просто подключаете скрипт в текущий контекст, а не глобально. Поэтому скрипты, которые вы определяете в шаблонах, а так же некоторые другие библиотеки, ожидающие глобального JQuery работать не будут.

Есть несколько вариантов решения проблемы. Для всех пакетов, которые вы подключаете через require, обеспечить доступ к $ или JQuery, можно добавив в файл webpack.config.js такую инструкцию:

/* подключим плагин */
var Encore = require('@symfony/webpack-encore');

Encore
   /* Установим путь куда будет осуществляться сборка */
   .setOutputPath('web/build/')
   /* ... */
  
   .autoProvidejQuery()

   /* В режиме разработки будем генерировать карту ресурсов */
   .enableSourceMaps(!Encore.isProduction());

/* Экспортируем финальную конфигурацию */
module.exports = Encore.getWebpackConfig();

Теперь все в порядке, однако скрипты, которые вы определяете в шаблонах по прежнему не будут видеть JQuery. В таком случае вероятно вам понадобится вручную добавить библиотеку в глобальную область видимости. Для этого отредактируем файл app.js:

var $ = require('./dist/jquery/jquery-3.2.1');
global.$ = global.jQuery = $;
require('./dist/bootstrap/js/bootstrap');

Еще раз запустим сборку и теперь у нас все очень компактно упаковано, разложено по каталогам, мы имеем один файл стилей и один файл скриптов. Все зависимости (шрифты, картинки) скопированы в соответствующие места.

Включение версионирования:

/* webpack.config.js */
// ...
.enableVersioning()
// ...

Если вы включили данную функцию, то вам потребуется внести некоторые настройки в конфигурацию вашего Symfony проекта:

# app/config/config.yml
framework:
    # ...
    assets:
        # Функционал доступен начиная с Symfony 3.3
        json_manifest_path: '%kernel.project_dir%/web/build/manifest.json'

Файл manifest.json, хранит карту соответствия файлов ресурсов их версионным аналогам. Теперь подключая в вашем Twig шаблоне стиль:

<link href="{{ asset('build/styles.css') }}" rel="stylesheet" />

на самом деле будет подключен файл вида: build/styles.c1a32e.css

Подключение стилей через JavaScript:

Вы вполне можете себе позволить импортировать файлы стилей через JavaScript. На примере нашего проекта можно было бы сделать так в app.js:

require('./app.scss');

var $ = require('./dist/jquery/jquery-3.2.1');
global.$ = global.jQuery = $;
require('./dist/bootstrap/js/bootstrap');

В этом случае, в webpack.config.js не нужно добавлять addStyleEntry. После сборки автоматически будет создан js файл и одноименный css файл со всеми запрошенными стилями в данном скрипте.

Деплой

Достаточно холиварная тема, но я все-таки затрону ее. Если вы предпочитаете производить сборку на стороне сервера, тогда вам стоит добавить в .gitignore каталог web/build и на продакшн сервере выполнять:

./node_modules/.bin/encore production

В режиме production ваши скрипты и стили будут дополнительно минифицированы.

Если же вам критично время развертки проекта на продакшене, то вы можете производить сборку ресурсов и коммитить уже готовые файлы в ваш репозиторий.

Заключение

Данный материал не претендует на использование в реальных условиях. В каждой конкретной ситуации будут свои подходы и настройки. Я лишь хотел показать еще один вариант управления ресурсами в проекте. Те кто знаком с webpack, вероятно найдут для себя полезной информацию о том, что появился такой плагин от разработчиков Symfony. Кто не знаком с webpack возможно заинтересуются этим инструментом.

Многие вещи хотелось бы описать более подробно, но сколько я ни пытался, все равно получался слишком раздутый пост. Я готов доработать материал, если будет адекватная критика. Ниже привожу ссылки, где можно более глубоко ознакомиться с данными инструментами:

Официальный сайт webpack: https://webpack.js.org/ ^[2]
Документация к плагину: http://symfony.com/doc/current/frontend.html ^[6]

Спасибо за внимание.

Автор: Владимир Т

Источник ^[7]