mix.md

Laravel 9 · Компиляция веб-активов с помощью Mix

• Введение
• Установка и настройка
• Запуск Mix
• Работа с таблицами стилей
  • Tailwind CSS
  • PostCSS
  • Sass
  • Обработка URL
  • Карты исходников CSS
• Работа с JavaScript
  • Vue
  • React
  • Извлечение сторонних библиотек
  • Пользовательская конфигурация Webpack
• Версионирование / очистка кеша
• Перезагрузка с помощью Browsersync
• Переменные окружения
• Уведомления

Введение

Laravel Mix – это пакет, разработанный создателем Laracasts Джеффри Уэй, предлагает гибкий API для определения шагов сборки Webpack для вашего приложения с использованием нескольких распространенных препроцессоров CSS и JavaScript.

Другими словами, Mix упрощает компиляцию и минимизацию файлов CSS и JavaScript вашего приложения. Посредством простой цепочки методов вы можете гибко определять свой сценарий по сборки веб-актива. Например:

mix.js('resources/js/app.js', 'public/js')
    .postCss('resources/css/app.css', 'public/css');

Если вы однажды были сбиты с толку и ошеломлены, начав работу с Webpack, то вам понравится Laravel Mix. Однако от вас не требуется использовать его при разработке приложения; вы можете использовать любой желаемый инструмент сборки, или даже не использовать его вовсе. Справедливо и обратное: вы можете использовать Laravel Mix без привязки вашего приложения к фреймворку Laravel.

Примечание
Если вам нужно начать разработку приложения с помощью Laravel и Tailwind CSS, ознакомьтесь с одним из наших стартовых комплектов приложения.

Установка и настройка

Установка Node

Перед запуском Mix вы должны сначала убедиться, что на вашем компьютере установлены Node.js и NPM:

node -v
npm -v

Вы можете легко установить последнюю версию Node и NPM с помощью простых графических установщиков с официального веб-сайта Node. Или, если вы используете Laravel Sail, вы можете вызывать Node и NPM через Sail:

./vendor/bin/sail node -v
./vendor/bin/sail npm -v

Установка Laravel Mix

Единственный оставшийся шаг – установить Laravel Mix. В свежей установке Laravel вы найдете файл package.json в вашем корневом каталоге. Файл package.json по умолчанию уже включает в себя все, что вам нужно для начала работы с Laravel Mix. Думайте об этом файле как о вашем файле composer.json, за исключением того, что он определяет зависимости Node вместо зависимостей PHP. Вы можете установить зависимости, на которые он ссылается, запустив:

npm install

Запуск Mix

Mix – это слой конфигурации поверх Webpack, поэтому для запуска задач Mix вам нужно только выполнить один из сценариев NPM, который содержится в файле package.json по умолчанию. Когда вы запускаете сценарии dev или production, все исходники активов CSS и JavaScript вашего приложения будут скомпилированы и помещены в каталог public приложения:

// Запустить все задачи Mix ...
npm run dev

// Запустить все задачи Mix и минифицировать на выходе ...
npm run prod

Наблюдение за изменениями исходников веб-активов

Команда npm run watch продолжит работу в консоли и будет следить за изменениями во всех соответствующих файлах CSS и JavaScript. Webpack автоматически перекомпилирует ваши исходники, когда обнаружит изменение в одном из этих файлов:

npm run watch

Webpack может не обнаруживать изменения ваших файлов в определенных локальных средах разработки. Если это наблюдается в вашей системе, рассмотрите возможность использования команды watch-poll:

npm run watch-poll

Работа с таблицами стилей

Файл webpack.mix.js вашего приложения является отправной точкой для компиляции всех веб-активов. Думайте об этом как о легкой конфигурационной обертке вокруг Webpack. Задачи Mix можно объединить в цепочку при определении того, как должны быть скомпилированы ваши веб-активы.

Tailwind CSS

Tailwind CSS – это современный, низкоутилитарный фреймворк для создания удивительных сайтов, не покидая HTML-разметку. Давайте рассмотрим, как начать использовать его в проекте Laravel совместно с Mix. Во-первых, мы должны установить Tailwind с помощью NPM и сгенерировать наш конфигурационный файл Tailwind:

npm install

npm install -D tailwindcss

npx tailwindcss init

Команда init сгенерирует файл tailwind.config.js. Раздел content этого файла позволяет вам настроить пути ко всем вашим шаблонам HTML, компонентам JavaScript и любым другим исходным файлам, которые содержат имена классов Tailwind, чтобы все классы CSS, не используемые в этих файлах, были удалены из вашего конечного файла CSS:

content: [
    './storage/framework/views/*.php',
    './resources/**/*.blade.php',
    './resources/**/*.js',
    './resources/**/*.vue',
    './vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php',
],

Затем вы должны добавить каждый из «слоев» Tailwind в файл resources/css/app.css вашего приложения:

@tailwind base;
@tailwind components;
@tailwind utilities;

После того, как вы указали необходимые слои Tailwind, необходимо обновить файл webpack.mix.js вашего приложения, чтобы скомпилировать ваш CSS, использующий Tailwind:

mix.js('resources/js/app.js', 'public/js')
    .postCss('resources/css/app.css', 'public/css', [
        require('tailwindcss'),
    ]);

Наконец, вы должны указать свою таблицу стилей в основном шаблоне макета вашего приложения. Многие разработчики приложений предпочитают хранить этот шаблон в resources/views/layouts/app.blade.php. Кроме того, убедитесь, что вы добавили метатег viewport, если он еще не присутствует:

<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link href="/css/app.css" rel="stylesheet">
</head>

PostCSS

PostCSS – мощный инструмент для преобразования вашего CSS, включен в Laravel Mix из коробки. По умолчанию Mix использует популярный плагин Autoprefixer для автоматического применения всех необходимых префиксов CSS3. Однако вы можете добавлять любые дополнительные плагины, подходящие для вашего приложения.

Сначала установите нужный плагин через NPM и включите его в свой массив плагинов при вызове метода postCss Mix. Метод postCss принимает путь к вашему файлу CSS в качестве первого аргумента, а в качестве второго аргумента – каталог, в который следует поместить скомпилированный файл:

mix.postCss('resources/css/app.css', 'public/css', [
    require('postcss-custom-properties')
]);

Или вы можете выполнить postCss без дополнительных плагинов, чтобы получить простую компиляцию и минификацию CSS:

mix.postCss('resources/css/app.css', 'public/css');

Sass

Метод sass позволяет вам скомпилировать Sass в CSS, понятный веб-браузерам. Метод sass принимает путь к вашему файлу Sass в качестве своего первого аргумента и каталог, в который должен быть помещен скомпилированный файл, в качестве второго аргумента:

mix.sass('resources/sass/app.scss', 'public/css');

Вы можете скомпилировать несколько файлов Sass в отдельные файлы CSS и даже настроить каталог назначения результирующего CSS, вызывая метод sass несколько раз:

mix.sass('resources/sass/app.sass', 'public/css')
    .sass('resources/sass/admin.sass', 'public/css/admin');

Обработка URL

Поскольку Laravel Mix построен поверх Webpack, важно понимать несколько концепций Webpack. Для компиляции CSS Webpack перезапишет и оптимизирует любые вызовы url() в ваших таблицах стилей. Хотя поначалу это может показаться странным, это невероятно мощная функциональность. Представьте, что мы хотим скомпилировать Sass, который включает относительный URL-адрес изображения:

.example {
    background: url('../images/example.png');
}

Предупреждение
Абсолютные пути для любого заданного url() будут исключены из перезаписи URL. Например, url('/images/thing.png') или url('http://example.com/images/thing.png') не будут изменены.

По умолчанию Laravel Mix и Webpack найдут example.png, скопируют его в вашу папку public/images, а затем перепишут url() в созданной вами таблице стилей. Таким образом, ваш скомпилированный CSS будет:

.example {
    background: url(/images/example.png?d41d8cd98f00b204e9800998ecf8427e);
}

Какой бы полезной ни была эта функция, возможно, что ваша существующая структура папок уже настроена так, как вам нравится. В этом случае вы можете отключить перезапись url() следующим образом:

mix.sass('resources/sass/app.scss', 'public/css').options({
    processCssUrls: false
});

После добавления этой записи в ваш файл webpack.mix.js, Mix больше не будет сопоставлять какой-либо url() или копировать веб-активы в ваш публичный каталог. Другими словами, скомпилированный CSS будет выглядеть так же, как вы его изначально указали:

.example {
    background: url("../images/thing.png");
}

Карты исходников CSS

Хотя по умолчанию они отключены, карты исходников могут быть активированы путем вызова метода mix.sourceMaps() в вашем файле webpack.mix.js. Хоть это и связано с затратами на компиляцию / производительность, но, в свою очередь, предоставит дополнительную отладочную информацию в инструментах разработчика вашего браузера при использовании скомпилированных веб-активов:

mix.js('resources/js/app.js', 'public/js')
    .sourceMaps();

Стиль сопоставления исходников

Webpack предлагает множество стилей сопоставления исходников. По умолчанию стиль сопоставления исходников Mix установлен как eval-source-map, что обеспечивает быстрое время перестроения. Если вы хотите изменить стиль сопоставления, то вы можете сделать это с помощью метода sourceMaps:

let productionSourceMaps = false;

mix.js('resources/js/app.js', 'public/js')
    .sourceMaps(productionSourceMaps, 'source-map');

Работа с JavaScript

Mix содержит несколько функций, которые помогут вам работать с вашими файлами JavaScript, например, компиляция современного ECMAScript, объединение модулей, минификация и объединение простых файлов JavaScript. Более того, все это работает без проблем, не требуя ни унции специального конфигурирования:

mix.js('resources/js/app.js', 'public/js');

Теперь, с помощью одной строчки кода вы можете воспользоваться следующими преимуществами:

• синтаксис современного EcmaScript.
• модули
• минификация для эксплуатационного режима.

Vue

Mix автоматически установит плагины Babel, необходимые для поддержки компиляции однофайловых компонентов Vue при использовании метода vue. Никакой дополнительной настройки не требуется:

mix.js('resources/js/app.js', 'public/js')
   .vue();

После того, как ваш JavaScript скомпилирован, вы можете ссылаться на него в своем приложении:

<head>
    <!-- ... -->

    <script src="/js/app.js"></script>
</head>

React

Mix автоматически установит плагины Babel, необходимые для поддержки React. Для начала добавьте вызов метода react:

mix.js('resources/js/app.jsx', 'public/js')
   .react();

За кулисами Mix загрузит и включит соответствующий плагин babel-preset-react Babel. После того, как ваш JavaScript скомпилирован, вы можете ссылаться на него в своем приложении:

<head>
    <!-- ... -->

    <script src="/js/app.js"></script>
</head>

Извлечение сторонних библиотек

Одним из потенциальных недостатков объединения всего кода JavaScript для конкретного приложения со сторонними библиотеками, такими как React и Vue, является то, что это затрудняет долгосрочное кеширование. Например, одно обновление кода вашего приложения заставит браузер повторно загрузить все сторонние библиотеки, даже если они не изменились.

Если вы намереваетесь часто обновлять JavaScript своего приложения, вам следует рассмотреть возможность извлечения всех сторонних библиотек в их собственный файл. Таким образом, изменение кода вашего приложения не повлияет на кеширование вашего большого файла vendor.js. Метод extract Mix делает это проще простого:

mix.js('resources/js/app.js', 'public/js')
    .extract(['vue'])

Метод extract принимает массив всех библиотек или модулей, которые вы хотите извлечь в файл vendor.js. Используя приведенный выше фрагмент в качестве примера, Mix сгенерирует следующие файлы:

• public/js/manifest.js: The Webpack manifest runtime
• public/js/vendor.js: Your vendor libraries
• public/js/app.js: Your application code

Чтобы избежать ошибок JavaScript, обязательно загружайте эти файлы в правильном порядке:

<script src="/js/manifest.js"></script>
<script src="/js/vendor.js"></script>
<script src="/js/app.js"></script>

Пользовательская конфигурация Webpack

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

Mix содержит полезный метод webpackConfig, который позволяет вам объединить небольшие переопределения конфигурации Webpack. Это особенно привлекательный вариант, поскольку он не требует от вас копирования и поддержки вашей собственной копии файла webpack.config.js. Метод webpackConfig принимает объект, который должен содержать любую специфичную для Webpack конфигурацию, которую вы хотите применить.

mix.webpackConfig({
    resolve: {
        modules: [
            path.resolve(__dirname, 'vendor/laravel/spark/resources/assets/js')
        ]
    }
});

Версионирование / очистка кеша

Многие разработчики дополняют имена своих скомпилированных веб-активов меткой времени или уникальным токеном, чтобы заставить браузеры загружать свежие активы вместо устаревших копий кода. Mix может автоматически обработать это за вас, используя метод version.

Метод version добавит уникальный хеш к именам файлов всех скомпилированных исходников, что сделает очистку кеша более удобной:

mix.js('resources/js/app.js', 'public/js')
    .version();

После создания файла версионирования вы не узнаете его точное имя. Итак, вы должны использовать глобальную функцию mix Laravel в вашем шаблоне для загрузки хешированного веб-актива. Глобальная функция mix фреймворка Laravel автоматически определит текущее имя хешированного файла:

<script src="{{ mix('/js/app.js') }}"></script>

Поскольку файлы с поддержкой версий обычно нужны только в эксплуатационном окружении, вы можете указать, чтобы процесс управления версиями выполнялся только во время запуска npm run prod:

mix.js('resources/js/app.js', 'public/js');

if (mix.inProduction()) {
    mix.version();
}

Изменение базовых URL-адресов с помощью Mix

Если ваши скомпилированные веб-активы Mix развернуты отдельно от вашего приложения в CDN, то вам нужно будет изменить базовый URL-адрес, генерируемый функцией mix. Вы можете сделать это, добавив параметр mix_url в конфигурационный файл config/app.php вашего приложения:

'mix_url' => env('MIX_ASSET_URL', null)

После указания URL-адреса, функция mix будет подставлять указанный префикс при создании URL-адресов для веб-активов:

https://cdn.example.com/js/app.js?id=1964becbdd96414518cd

Перезагрузка с помощью Browsersync

BrowserSync может автоматически отслеживать изменения в ваших файлах и вносить изменения в браузер, не требуя обновления страницы вручную. Вы можете включить эту поддержку, вызвав метод mix.browserSync():

mix.browserSync('laravel.test');

Параметры BrowserSync можно указать путем передачи объекта JavaScript в метод browserSync:

mix.browserSync({
    proxy: 'laravel.test'
});

Затем запустите сервер разработки Webpack с помощью команды npm run watch. Теперь, когда вы изменяете скрипт или файл PHP, вы можете наблюдать, как браузер мгновенно обновляет страницу, чтобы отразить ваши изменения.

Переменные окружения

Вы можете использовать переменные окружения в своем webpack.mix.js, добавив к одной из переменных префикс MIX_ в вашем файле .env:

MIX_SENTRY_DSN_PUBLIC=http://example.com

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

process.env.MIX_SENTRY_DSN_PUBLIC

Уведомления

Когда доступно, Mix будет автоматически отображать уведомления ОС при компиляции, давая вам мгновенную информацию о том, была ли компиляция успешной или нет. Однако, могут быть случаи, когда вы предпочтете отключить эти уведомления. Одним из таких примеров может быть запуск Mix на вашем рабочем сервере. Уведомления можно отключить с помощью метода disableNotifications:

mix.disableNotifications();