Компіляція активів (Mix)

• Вступ
• Встановлення та налаштування
• Running Mix
• Робота з таблицями стилів
  • Less
  • Sass
  • Stylus
  • PostCSS
  • Звичайний CSS
  • Обробка URL-адрес
  • Карти Source
• Робота з JavaScript
  • Вилучення Vendor
  • Зреагуйте
  • Ваніль JS
  • Спеціальна конфігурація Webpack
• Копіювання файлів та каталогів
• Переробка версій / кеш-пам’яті
• Перезавантаження синхронізації браузера
• Змінні середовища
• Повідомлення

Вступ

Laravel Mixзабезпечує вільний API для визначення кроків побудови Webpack для вашого додатку Laravel за допомогою декількох поширених попередніх процесорів CSS та JavaScript. За допомогою простого ланцюжка методів ви можете вільно визначити конвеєр активів. Наприклад:

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

Якщо ви коли-небудь були розгублені та пригнічені щодо початку роботи з Webpack та компіляцією активів, вам сподобається Laravel Mix. Однак вам не потрібно використовувати його під час розробки вашого додатка; Ви можете використовувати будь-який інструмент конвеєру активів, який хочете, а то й взагалі жоден.

Встановлення та налаштування

Встановлення Node

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

node -v
npm -v

За замовчуванням Laravel Homestead включає все необхідне; однак, якщо ви не використовуєте Vagrant, ви можете легко встановити останню версію Node і NPM, використовуючи прості графічні інсталятори відїх сторінку завантаження.

Laravel Mix

Залишається лише встановити Laravel Mix. У свіжій інсталяції Laravel ви знайдетеpackage.jsonфайл у кореневій частині вашої структури каталогів. За замовчуваннямpackage.jsonфайл містить усе необхідне для початку роботи. Думай про це як про своєcomposer.jsonфайл, за винятком того, що він визначає залежності Node замість PHP. Ви можете встановити залежності, на які посилається, запустивши:

npm install

Running Mix

Mix - це конфігураційний шар поверхВеб-пакет, тому для запуску завдань Mix вам потрібно лише виконати один із сценаріїв NPM, який входить до складу Laravel за замовчуваннямpackage.jsonфайл:

// Run all Mix tasks...
npm run dev

// Run all Mix tasks and minify output...
npm run production

Спостереження за активами для змін

npm run watchкоманда продовжить працювати у вашому терміналі та відстежуватиме всі відповідні файли на наявність змін. Потім Webpack автоматично перекомпілює ваші Assets, коли виявить зміни:

npm run watch

Ви можете виявити, що в певних середовищах Webpack не оновлюється, коли файли змінюються. Якщо це так у вашій системі, подумайте про використанняwatch-pollкоманда:

npm run watch-poll

Робота з таблицями стилів

webpack.mix.jsфайл - це точка входу для компіляції всіх активів. Подумайте про це як про легку обгортку конфігурації навколо Webpack. Поєднання завдань можна об’єднати в ланцюжок, щоб точно визначити, як слід компілювати ваші Assets.

Less

lessметод може бути використаний для компіляціїLessв CSS. Складемо наш основнийapp.lessчувакpublic/css/app.css.

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

Кілька дзвінків наlessметод може бути використаний для компіляції декількох файлів:

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

Якщо ви хочете налаштувати ім'я файлу скомпільованого CSS, ви можете передати повний шлях до файлу як другий аргумент доlessметод:

mix.less('resources/less/app.less', 'public/stylesheets/styles.css');

Якщо вам потрібно замінитиосновні опції Less плагінів, ви можете передати об'єкт як третій аргументmix.less():

mix.less('resources/less/app.less', 'public/css', {
    strictMath: true
});

Sass

sassметод дозволяє компілюватиSassв CSS. Ви можете використовувати метод приблизно так:

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

Знову ж, якlessметоду, ви можете скомпілювати кілька файлів Sass у власні відповідні файли CSS і навіть налаштувати вихідний каталог отриманого CSS:

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

ДодатковіПараметри плагіна Node-Sassможе бути поданий як третій аргумент:

mix.sass('resources/sass/app.sass', 'public/css', {
    precision: 5
});

Stylus

Подібно до Less і Sass,stylusметод дозволяє компілюватиStylusв CSS:

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

Ви також можете встановити додаткові плагіни Stylus, такі якПорушення. Спочатку встановіть плагін через NPM (npm install rupture), а потім вимагайте цього у своєму дзвінкуmix.stylus():

mix.stylus('resources/stylus/app.styl', 'public/css', {
    use: [
        require('rupture')()
    ]
});

PostCSS

PostCSS, потужний інструмент для перетворення вашого CSS, включений до Laravel Mix з коробки. За замовчуванням Mix використовує популярнеАвтопрефіксплагін для автоматичного застосування всіх необхідних префіксів постачальника CSS3. Однак ви можете вільно додавати будь-які додаткові плагіни, які підходять для вашої програми. Спочатку встановіть потрібний плагін через NPM, а потім посилайтеся на нього у своємуwebpack.mix.jsфайл:

mix.sass('resources/sass/app.scss', 'public/css')
    .options({
        postCss: [
            require('postcss-css-variables')()
        ]
    });

Звичайний CSS

Якщо ви просто хочете об'єднати кілька простих таблиць стилів CSS в один файл, ви можете використовувати файлstylesметод.

mix.styles([
    'public/css/vendor/normalize.css',
    'public/css/vendor/videojs.css'
], 'public/css/all.css');

Обробка 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 та Webpackexample.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");
}

Карти Source

Хоча за замовчуванням вимкнено, вихідні карти можуть бути активовані за допомогою викликуmix.sourceMaps()метод у вашомуwebpack.mix.jsфайл. Незважаючи на те, що він має вартість компіляції / продуктивності, це забезпечить додаткову інформацію про Debugging інструментів розробника вашого браузера при використанні скомпільованих ресурсів.

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

Стиль зіставлення джерел

Webpack пропонує безлічстилі відображення джерел. За замовчуванням для стилю зіставлення Source Mix встановлено значенняeval-source-map, що забезпечує швидкий час відновлення. Якщо ви хочете змінити стиль відображення, ви можете зробити це за допомогоюsourceMapsметод:

let productionSourceMaps = false;

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

Робота з JavaScript

Mix надає кілька функцій, які допоможуть вам працювати з вашими файлами JavaScript, такі як компіляція ECMAScript 2015, групування модулів, мініфікація та конкатенація простих файлів JavaScript. Ще краще, все це працює безперешкодно, не вимагаючи ні грама власної конфігурації:

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

За допомогою цього одного рядка коду ви тепер можете скористатися:

• ES2015 syntax.
• Modules
• Compilation of .vue files.
• Minification for production environments.

Вилучення Vendor

Одним з можливих недоліків об’єднання всіх специфічних для додатків JavaScript із вашими бібліотеками постачальників є те, що це ускладнює довгострокове кешування. Наприклад, одне оновлення коду вашої програми змусить браузер повторно завантажити всі ваші бібліотеки постачальників, навіть якщо вони не змінилися.

Якщо ви маєте намір регулярно оновлювати JavaScript вашого додатка, вам слід розглянути можливість вилучення всіх бібліотек постачальників у їх власний файл. Таким чином, зміна коду програми не вплине на кешування великого файлуvendor.jsфайл. Міксextractметод робить це вітряком:

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>

Зреагуйте

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

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

За лаштунками Mix завантажить та включить відповіднеbabel-preset-reactПлагін Babel.

Ваніль JS

Подібно до поєднання таблиць стилів зmix.styles(), Ви також можете комбінувати та зменшувати будь-яку кількість файлів JavaScript ізscripts()метод:

mix.scripts([
    'public/js/admin.js',
    'public/js/dashboard.js'
], 'public/js/all.js');

Цей параметр особливо корисний для застарілих проектів, де вам не потрібна компіляція Webpack для вашого JavaScript.

Невелика варіаціяmix.scripts()єmix.babel(). Його підпис методу ідентичнийscripts; однак, об'єднаний файл отримає компіляцію Babel, яка перекладе будь-який код ES2015 у ванільний JavaScript, який зрозуміють всі браузери.

Спеціальна конфігурація Webpack

За лаштунками Laravel Mix посилається на попередньо налаштованийwebpack.config.jsфайл, щоб якнайшвидше розпочати роботу. Іноді вам може знадобитися вручну змінити цей файл. Можливо, у вас є спеціальний завантажувач або плагін, на який потрібно посилатися, або, можливо, ви віддаєте перевагу використовувати Stylus замість Sass. У таких випадках у вас є два варіанти:

Злиття власної конфігурації

Мікс забезпечує кориснеwebpackConfigметод, який дозволяє об'єднати будь-які короткі заміни конфігурації Webpack. Це особливо привабливий вибір, оскільки він не вимагає копіювати та зберігати власну копіюwebpack.config.jsфайл.webpackConfigметод приймає об'єкт, який повинен містити будь-якийКонфігурація веб-пакетащо ви хочете подати заявку.

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

Файли спеціальної конфігурації

Якщо ви хочете повністю налаштувати конфігурацію Webpack, скопіюйте файлnode_modules/laravel-mix/setup/webpack.config.jsфайл у кореневий каталог вашого проекту. Далі вкажіть усі--configпосилання у вашомуpackage.jsonфайл у щойно скопійований файл конфігурації. Якщо ви вирішите застосувати такий підхід до налаштування, будь-які майбутні оновлення Mix'swebpack.config.jsповинні бути вручну об’єднані у ваш налаштований файл.

Копіювання файлів та каталогів

copyметод може бути використаний для копіювання файлів та каталогів у нові місця. Це може бути корисно, коли певний актив у вашомуnode_modulesкаталог потрібно перенести у вашpublicпапку.

mix.copy('node_modules/foo/bar.css', 'public/css/bar.css');

При копіюванні каталогу файлcopyметод згладить структуру каталогу. Щоб зберегти оригінальну структуру каталогу, слід використовуватиcopyDirectoryзамість цього:

mix.copyDirectory('resources/img', 'public/img');

Переробка версій / кеш-пам’яті

Багато розробників суфіксують свої скомпільовані ресурси з позначкою часу або унікальним маркером, щоб змусити браузери завантажувати нові ресурси, а не обслуговувати застарілі копії коду. Mix може впоратися з цим, використовуючиversionметод.

versionметод автоматично додає унікальний хеш до імен усіх скомпільованих файлів, що дозволяє зручніше перебити кеш:

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

Після генерації версійного файлу ви не будете знати точної назви файлу. Отже, вам слід використовувати глобальний Laravelmixфункція у вашомупоглядизавантажити належним чином хешований актив.mixфункція автоматично визначає поточну назву хешованого файлу:

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

Оскільки версійні файли, як правило, непотрібні при розробці, ви можете доручити процесу керування версіями запускатися лише протягомnpm run production:

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

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

Спеціальні базові URL-адреси міксів

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

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

Після налаштування URL-адреси змішування,mixфункція буде префіксувати налаштовану URL-адресу при генерації URL-адрес для активів:

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

Перезавантаження синхронізації браузера

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

mix.browserSync('my-domain.test');

// Or...

// https://browsersync.io/docs/options
mix.browserSync({
    proxy: 'my-domain.test'
});

Ви можете передати рядок (проксі-сервер) або об’єкт (налаштування BrowserSync) цьому методу. Далі запустіть сервер розробників Webpack за допомогоюnpm run watchкоманди. Тепер, коли ви змінюєте скрипт або файл PHP, спостерігайте, як браузер миттєво оновлює сторінку, щоб відобразити ваші зміни.

Змінні середовища

Ви можете вводити змінні середовища в Mix, додавши до вашого ключа префікс ключа.envфайл зMIX_:

MIX_SENTRY_DSN_PUBLIC=http://example.com

Після того, як змінна була визначена у вашому.envфайл, ви можете отримати до нього доступ черезprocess.envоб'єкт. Якщо значення змінюється під час запускуwatchзавдання, вам потрібно буде перезапустити завдання:

process.env.MIX_SENTRY_DSN_PUBLIC

Повідомлення

Якщо доступний, Mix автоматично відображатиме повідомлення ОС для кожного пакета. Це дасть вам миттєвий зворотний зв’язок щодо успішної компіляції чи ні. Однак можуть траплятися випадки, коли ви віддаєте перевагу вимкнути ці Notification. Одним з таких прикладів може бути активація Mix на вашому виробничому сервері. Повідомлення можуть бути деактивовані черезdisableNotificationsметод.

mix.disableNotifications();