Установка Encore

Дата обновления перевода 2024-07-25

Установка 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, вам понадобится создать все эти новые каталоги и файлы самостоятельно, cледуя инструкциям в следующем разделе.

Установка Encore в не-Symfony приложениях

Установите Encore в ваш проект через Yarn:

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

Эта команда создает (или изменяет) файл package.json и скачивает зависимости в каталог node_modules/. Yarn также создает/обновляет yarn.lock (под названиемpackage-lock.json, если вы используете npm).

Tip

Вы должны отправить package.json и yarn.lock (или 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
     *
     * Добавьте одну запись 1 для каждой "страницы" вашего приложения
     * (включая те, которые есть на каждой странице - например, "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, которые включают функции вроде версионирования и разделения кода (split chunks).