Devim Front: Webpack config

Конфигурация Webpack для проектов на TS+React.

Установка

1. Подключите неявные dev-зависимости проекта (если они ещё не были установлены):

npm i -D webpack typesciprt @babel/core

2. Подключите библиотеку в dev-зависимости проекта:

npm i -D @devim-front/webpack-config

3. Создайте файл webpack.config.js в корне своего проекта со следующим содержанием:

const { createConfig } = require('@devim-front/webpack-config');

module.exports = (env, args) =>
  createConfig(env, args, {
    rootPath: __dirname,
  });

Полный список настроек для createConfig читайте ниже.

4. Создайте файл tsconfig.json в корне своего проекта. Рекомендуется использовать общую конфигурацию из пакета @devim-front/tsconfig.

5. Создайте файл .babelrc в корне своего проекта. Рекомендуется использовать общую конфигурацию из пакета @devim-front/babel-config.

6. Создайте файл .postcssrc.js в корне проекта. Рекомендуется использовать общую конфигурацию из пакета @devim-front/postcss-config.

API

В данном разделе представлено описание функций библиотеки.

createConfig(env, args, options = {})

Возвращает объект конфигурации webpack.

Название параметра	Тип	Описание
env	Object	Коллекция переменных среды, заданная через webpack.
args	Object	Коллекция именованных аргументов коммандной строки.
options	Object	Коллекция настроек сборки.

createConfig.options

Перед тем, как говорить о настройках функции createConfig, следует вкратце очерить её функционал. Сборка, возвращаемая этой функцией, может работать в двух режимах и для двух сред выполнения.

Режимы сборки - development и production. development используется для отладки и тестирования, production - для боевого сервера. Режим сборки берется из переменной окружения NODE_ENV, по умолчанию - development.

Доступные целевые среды: node и web. В первом режиме код оптимизируется для выполнения на NodeJS (серверная часть проекта), во втором - для выполнения в браузере. Целевая среда сборки берётся из аргумента командной строки --target, по умолчанию web. В дальнейшем, сборка с --target=web будет называтся клиентской, а с --target=node - серверной.

rootPath: string

Абсолютный путь к каталогу с проектом. Из файла webpack.config.js его можно получить, используя константу __dirname. По умолчанию rootPath равен process.cwd().

sourcePath: string

Путь к каталогу с исходным кодом проекта относительно его корня (rootPath). По умолчанию это каталог ./src.

outputPath: string

Путь к каталогу, в которой происходит сборка относительно корня проекта rootPath. По умолчанию это каталог ./build.

publicPath: string

Путь к каталогу со статическими файлами относительно корня проекта rootPath. При сборке эти файлы копируются в outputPath без каких-либо преобразований. Например, если в корень сайта следует поместить файл robots.txt, его следует положить в publicPath. По умолчанию это каталог ./public.

entry: string

Имя файла - точки сборки проекта без расширения относительно каталога с исходным кодом (sourcePath). Например, если ваша точка входа - ./src/index.ts, то в entry следует вписать просто index (относительно ./src и без расширения). По умолчанию, для сборки клиентской части entry равно index, для сборки серверной - server/index (что обычно соответствует файлам ./src/index.ts и ./src/server/index.ts).

При создании объекта конфигурации функция createConfig ищёт существующий файл с именем entry в sourcePath, добавляя к нему расширения из списка: .tsx, .ts, .jsx, .js. Первый найденный файл станет реальной точкой сборки. Кроме того, для найденной точки входа createConfig пытается подобрать HTML-шаблон, по аналогичному алгоритму, только список допустимых расширений - .ejs и .html. Если файл с HMTL-шаблоном не существует, конфигурация не станет генерировать HTML.

К примеру, в каталоге ./src находятся файлы ./index.js - точка сборки, и index.ejs - HTML-шаблон для неё. Тогда следует указать в настройках entry: 'index'. Если вы поменяете расширения этих файлов, конфигурацию можно не трогать. Но если вы измение имя одно из них, то либо сборка завершится неудачно (не найдена точка входа), либо не сгенерируется HTML.

outputJs: string

Шаблон имени итоговых JS-файлов. По умолчанию это js/\[name\].\[contenthash\].js для клиентской сборки, и server.js для серверной. Подробнее о шаблонах можно почитать в документации webpack.

outputCss: string

Шаблон имени итоговых CSS-файлов. По умолчанию это css/\[name\].\[contenthash\].css для клиентской сборки; серверная же сборка css-файлов не генерирует. Подробнее о шаблонах можно почитать в документации webpack.

outputHtml: string

Шаблон имени итогового HTML-файла. По умолчанию это index.html для клиентской сборки, серверная же сборка не генерирует HTML-файлов.

outputFiles: string

Имя каталога, в который следует поместить все прочие файлы, подключаемые в сборке, относительно outputPath. По умолчанию это files (что соответствует каталогу ./build/files). Данная опция используется только при клиентской сборке, поскольку серверная не генерирует дополнительных файлов.

port: number

Номер порта, на котором запускается проект. По умолчанию для клиентской части это 3000, для серверной - 8000. Данные номера будут использованы как в конфигурации webpack-dev-server, так и проброшены в исходный код через переменную APP_LISTEN, чтобы запустить на указанном порту сервер на NodeJS.

proxy: Object

Инструкции для проксирования запросов webpack-dev-server. Подробнее об этом механизме можно прочитать в документации. По умолчанию - {}.

server: Object и client: Object

В свойствах server и client можно указать специфические настройки, которые будут работать только указанной целевой среды сборки. В server и client можно указать все вышеперечисленные настройки, кроме rootPath. К примеру, мы хотим объявить разные точки сборки и порты для каждой среды выполнения:

const { createConfig } = require('@devim-front/webpack-config');

module.exports = (env, args) =>
  createConfig(env, args, {
    rootPath: __dirname,
    client: {
      entry: 'index',
      port: 3000,
    },
    server: {
      entry: 'server/index',
      port: 8000,
    },
  });

Показанная конфигурация будет использовать точку входа ./src/index.ts и порт 3000 для клиентской части, и точку входа ./src/server/index.ts на порту 8000 для серверной части.