Установка Encore

Дата оновлення перекладу 2024-05-27

Установка Encore

По-перше, переконайтеся, що ви встановили Node.js. Потім дотримуйтесь інструкцій нижче, які залежать від того, чи встановлюєте ви Encore у додатку Symfony, чи ні.

Установка Encore у додатку Symfony

Виконайте ці команди, щоб встановити залежності PHP та JavaScript у вашому проекті:

1
2
$ composer require symfony/webpack-encore-bundle
$ npm install

Якщо ви використовуєте Symfony Flex , це встановить та підключить WebpackEncoreBundle, створіть каталог assets/, додайте файл webpack.config.js, та додайте node_modules/ до .gitignore. Ви можете пропустити решту цієї статті та йти писати ваш перший JavaScript і CSS, прочитавши Encore: Налаштування вашого проекту!

Якщо ви не використовуєте Symfony Flex, вам знадобиться створити всі ці нові каталоги та файли самостійно, слідуючи інструкціям у наступному розділі.

Установка Encore у не-Symfony додатках

Встановіть Encore у проект через npm:

1
$ npm install @symfony/webpack-encore --save-dev

Ця команда створює (або змінює) файл package.json і завантажує залежності у каталог node_modules/.

Tip

Ви маєте відправити package.json та package-lock.json (або package-lock.json при використанні npm) контролю версій, але не ігнорувати node_modules/.

Створення файлу webpack.config.js

Далі, створіть новий файл webpack.config.js в корені вашого проекту. Це головний файл конфігурації як дла Webpack, так і для Webpack Encore:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
const Encore = require('@symfony/webpack-encore');

// Вручну сконфігуруйте операційне середовище, якщо воно ще не сконфігуроване командою "encore".
// Це корисно коли ви використовуєте інструменти, які покладаються на файл webpack.config.js.
if (!Encore.isRuntimeEnvironmentConfigured()) {
    Encore.configureRuntimeEnvironment(process.env.NODE_ENV || 'dev');
}

Encore
    // каталог, де будуть зберігатися скомпільовані ресурси
    .setOutputPath('public/build/')
    // публічний шлях, який використовується веб-сервером для доступу до шляху виведення
    .setPublicPath('/build')
    // необхідно лише для розгортання CDN або суб-каталогу
    //.setManifestKeyPrefix('build/')

    /*
     * ENTRY CONFIG
     *
     * Додайте один запис для кожної "сторінки" вашого додатку
     * (включно з тими, які є на кожній сторінці - наприклад, "app")
     *
     * Кожний запис стане в результаті одним файлом JavaScript (наприклад, app.js)
     * та одним файлом CSS (наприклад, app.css) якщо ваш JavaScript імпортує CSS.
     */
    .addEntry('app', './assets/app.js')
    //.addEntry('page1', './assets/page1.js')
    //.addEntry('page2', './assets/page2.js')

    // Якщо підключений, Webpack "розділяє" ваші файли на менші частини для більшої мінімізації.
    .splitEntryChunks()

    // буде вимагати додатковий тег скрипту для runtime.js
    // але, вам скоріш за все це не буде потрібно, хіба що ви не створюєте застосунок однієї сторінки
    .enableSingleRuntimeChunk()

    /*
     * FEATURE CONFIG
     *
     * Підключіть та сконфігуруйте інші функції нижче. Щоб побачити повний перелік
     * функцій, див.:
     * https://symfony.com/doc/current/frontend.html#adding-more-features
     */
    .cleanupOutputBeforeBuild()
    .enableBuildNotifications()
    .enableSourceMaps(!Encore.isProduction())
    // вмикає хешовані імена файлів (наприклад, app.abc123.css)
    .enableVersioning(Encore.isProduction())

    // вмикає полізаповнення @babel/preset-env
    .configureBabelPresetEnv((config) => {
        config.useBuiltIns = 'usage';
        config.corejs = 3;
    })

    // вмикає підтримку Sass/SCSS
    //.enableSassLoader()

    // розкоментуйте, якщо ви використовуєте TypeScript
    //.enableTypeScriptLoader()

    // розкоментуйте, щоб отримати атрибути integrity="..." вашого скрипту та тегів посилання
    // вимагає WebpackEncoreBundle 1.4 або новіше
    //.enableIntegrityHashes(Encore.isProduction())

    // розкоментуйте, якщо у вас є проблеми з плагіном jQuery
    //.autoProvidejQuery()

    // розкоментуйте, якщо ви використовуєте API Platform Admin (композитор вимагає api-admin)
    //.enableReactPreset()
    //.addEntry('admin', './assets/admin.js')
;

module.exports = Encore.getWebpackConfig();

Створення іншого файлу підтримки

Далі, відкрийте новий файл assets/app.js, який містить деякий код JavaScript та імпортує деякий:

1
2
3
4
5
6
7
8
9
10
11
12
13
// assets/app.js
/*
 * Вітаємо в головному файлі JavaScript вашого додатку!
 *
 * Ми рекомендуємо додавати вбудовану версію цього файлу JavaScript
 * (та його CSS-файл) у ваш базовий макет (base.html.twig).
 */

// будь-який CSS, який ви імпортуєте, буде виводитися в один css-файл (в цьому випадку - app.css)
import './styles/app.css';

// запустити додаток Stimulus
import './bootstrap';

Додайте новий файл assets/styles/app.css:

1
2
3
4
/* assets/styles/app.css */
body {
    background-color: lightgray;
}

Ви маєте також додати файл assets/bootstrap.js, який ініціалізує Stimulus: систему, про яку ви скоро дізнаєтеся:

1
2
3
4
5
6
7
8
9
10
11
12
// assets/bootstrap.js
import { startStimulusApp } from '@symfony/stimulus-bridge';

// Реєструє контролери Stimulus з controllers.json та у каталозі controllers/
export const app = startStimulusApp(require.context(
    '@symfony/stimulus-bridge/lazy-controller-loader!./controllers',
    true,
    /\.(j|t)sx?$/
));

// зареєструвати будь-які користувацькі сторонні контролери тут
// app.register('some_controller_name', SomeImportedController);

Потім створіть файл assets/controllers.json, який також підходить до системи Stimulus:

1
2
3
4
{
    "controllers": [],
    "entrypoints": []
}

Нарешті, хоча це й не обовʼязково, додайте наступні scripts до вашого файлу package.json, щоб ви могли виконувати однакові команди у решті документації:

1
2
3
4
5
6
"scripts": {
    "dev-server": "encore dev-server",
    "dev": "encore dev",
    "watch": "encore dev --watch",
    "build": "encore production --progress"
}

Ви налаштуєте та дізнаєтеся більше про ці файли у Encore: Налаштування вашого проекту. Коли ви запустсите Encore, він попросить вас встановити ще декілька залежностей, базуючиссь на тому, які функції Encore ви підключили.

Caution

Деяка документація використовуватиме функції, специфічні для Symfony або WebpackEncoreBundle Symfony. Вони необов'язкові та є особливими способами вказування на шляхи ресурсів, згенерованих Encore, які вмикають функції на кшталт версіонування та розділення коду.