arui-scripts 15.6.0 → 15.6.1

package/docs/artifact.md

@@ -0,0 +1,58 @@
+Настройки сборки артефакта
+===
+
+## docker
+
+По-умолчанию, базовым образом для сборки артефакта является [alpine-node-nginx](../../alpine-node-nginx).
+
+На `8080` порту будет поднят nginx, который будет раздавать статику и проксировать все остальные запросы к `nodejs`.
+
+Вы также можете переопределить полностью процесс сборки docker-образа используя механизм [overrides](#тонкая-настройка)
+или создав в корневой директории проекта `Dockerfile` содержащий необходимый набор инструкций.
+Пример [Dockerfile](src/templates/dockerfile.template.ts).
+
+`Dockerfile` в корне проекта имеет приоритет над overrides.
+
+Чтобы переопределить скрипт запуска, воспользуйтесь механизмом [overrides](#тонкая-настройка)
+или создайте в корневой директории проекта `start.sh` файл содержащий необходимый набор инструкций.
+Пример [start.sh](src/templates/start.template.ts).
+
+`start.sh` в корне проекта имеет приоритет над overrides.
+
+
+## Концигурация nginx
+Несмотря на то, что nginx имеет готовый конфиг с роутингом, иногда возникает необходимость добавлять свои роуты.
+Вы можете использовать механизм [overrides](overrides.md).
+Так же вы можете создать `nginx.conf` на уровне проекта со своими роутами. Пример конфига [тут](../src/templates/nginx.conf.template.ts).
+Файл nginx.conf имеет приоритет над оверрайдами.
+
+### Использование env переменных в nginx.conf
+
+Иногда у вас может возникнуть потребность переопределять какие-то из настроек nginx в зависимости
+от среды, на которой запущен контейнер. Это можно сделать задав свой `nginx.conf` и передав ENV переменные
+в контейнер. По умолчанию конфигурация nginx прогоняется при старте
+через [envsubst](https://www.gnu.org/software/gettext/manual/html_node/envsubst-Invocation.html).
+
+Если вы используете свой базовый docker-образ для работы приложения - убедитесь что в нем доступен `envsubst`.
+Для alpine он является частью пакета [`gettext`](https://pkgs.alpinelinux.org/contents?branch=edge&name=gettext&arch=x86&repo=main)
+
+**Важно**. Для того чтобы сохранить нормальную работу специальных переменных nginx, типа `$proxy_add_x_forwarded_for`
+перед запуском envsubst они будут заменены на `~~proxy_add_x_forwarded_for~~`, а затем возвращены в исходный вид.
+envsubst будет заменять переменные записанные **только** как `${MY_VAR}`.
+
+
+Вы можете использовать это так:
+
+```nginx.conf
+server {
+    listen 8080;
+    server_name ${SERVICE_NAME};
+    ...
+}
+```
+
+```shell
+docker run my-awesome-app --env SERVICE_NAME=my-app
+```
+
+После запуска nginx будет иметь server_name `my-app`.

package/docs/caveats.md

@@ -0,0 +1,30 @@
+Особенности поведения
+===
+
+## node-externals
+
+Сборка серверной части устроена таким образом, что большая часть `node_modules` не попадает в сборку (в файл `.build/server.js`),
+а загружается стандартным `require` node.js.
+Основной мотивацией для это являются многие старые пакеты, которые делают "странные" вещи с require - например, пытаются
+подключать файлы динамически, используют `require.extensions` и т.д. Это может приводить к ошибкам сборки или даже к
+ошибкам во время выполнения.
+
+Но в случае react-компонентов, мы зачастую запрашиваем кроме кода компонентов еще и `.css`, `.png` и другие файлы.
+`require` из node.js на таких местах ломается. Поэтому наши внутренние библиотеки компонентов все же должны попадать в
+собранный файл `.build/server.js`. Всё это сделано с помощью [добавления их в исключение](src/configs/webpack.server.dev.ts#L59)
+плагина [webpack-node-externals](https://www.npmjs.com/package/webpack-node-externals).
+В случае, если вам необходима обработка не-js файлов из других внешних модулей - вы можете
+воспользоваться механизмом `overrides`, и ключом `serverExternalsExemptions`.
+По умолчанию же все не-js файлы из внешних модулей будут проигнорированы.
+
+## Кеширование сборки
+В dev сборке для сервера и клиента настроено кеширование. Оно должно нормально работать когда вы просто работаете
+над проектом - меняете ваш код, ставите новые зависимости и тд.
+
+Но когда вы руками меняете код внутри node_modules - вы не сможете увидеть ваши изменения, так как webpack будет
+использовать данные из кеша. Для того чтобы ваши изменения применились в сборке вам необходимо очистить кеш
+webpack и перезапустить сборку. Кеши хранятся в папке `.cache` внутри `node_modules` вашего проекта.
+
+```
+rm -rf ./node_modules/.cache
+```

package/docs/commands.md

@@ -0,0 +1,123 @@
+Доступные команды
+===
+
+### start
+Запускает dev-сервер для клиентского кода и серверный код в watch-режиме.
+
+**Как запустить?**
+```bash
+arui-scripts start
+```
+
+### start:prod
+Запускает dev-сервер для клиентского кода и серверный код в watch-режиме. При этом использует production-конфигурацию для webpack.
+Может быть полезна для сбора метрик производительности.
+
+**Как запустить?**
+```bash
+arui-scripts start:prod
+```
+
+### build
+Собирает клиентский и серверный код в production-режиме.
+
+**Как запустить?**
+```bash
+arui-scripts build
+```
+
+### test
+Команда `arui-scripts test` внутри запускает jest с дополнительной конфигурацией.
+
+Конфигурация включает в себя:
+- Использование `jest-snapshot-serializer-class-name-to-string` для правильной работы с `cn`
+- Замену всех импортов css файлов на пустые файлы
+- Компиляцию .js/.jsx файлов используя babel
+- Компиляцию .ts/.tsx файлов используя tsc
+- Замену импортов остальных типов файлов на импорт строк с названием файла
+
+По умолчанию под маску для поиска тестов попадают все файлы `*test*.(js|jsx|ts|tsx)`, `*spec*.((js|jsx|ts|tsx))`, `*/__test__/*.(js|jsx|ts|tsx)`.
+
+Вы можете переопределять любые настройки jest в `package.json`, [документация](https://facebook.github.io/jest/docs/en/configuration.html).
+
+Если какие либо из ваших инструментов (например VSСode или WebStorm) не могут запустить тесты поскольку не находят конфигурацию, вы можете так же указать `arui-scripts` как preset для jest.
+Таким образом будет работать как запуск тестов через arui-script, так и любые сторонние инструменты, запускающие jest.
+
+_package.json_
+```json
+{
+    "jest": {
+        "preset": "arui-scripts"
+    }
+}
+```
+
+**Как запустить?**
+```bash
+arui-scripts test
+```
+
+### docker-build
+Собирает клиентский и серверный код в production-режиме, создает docker-образ и пушит его в docker-репозиторий.
+
+**Как запустить?**
+```bash
+arui-scripts docker-build
+```
+
+Имя контейнера определяется как `{configs.dockerRegistry}/{name}:{version}`. Переменные `name` и `version` по умолчанию берутся из package.json,
+но вы так же можете переопределить их из командной строки, например
+`arui-scripts docker-build name=container-name version=0.1-beta`.
+
+Команда предполагает наличие установленных `node_modules` перед сборкой, в процессе работы же очищает дев зависимости используя `yarn` или `npm`.
+yarn будет использоваться когда в рутовой папке проекта есть `yarn.lock` и `yarn` доступен в системе.
+Если вы используете yarn 2, для выполнения команды очистки используется плагин [workspace-tools](https://github.com/yarnpkg/berry/blob/HEAD/packages/plugin-workspace-tools/README.md), поэтому он должен быть установлен и указан в `.yarnrc.yml` вашего проекта.
+
+Итоговый контейнер будет содержать `nginx` и скрипт для запуска `nginx` одновременно с `nodejs` сервером.
+
+В итоге, для корректного запуска вашего докер-контейнера вам надо будет выполнить команду
+
+```bash
+docker run -p 8080:8080 container-name:version ./start.sh
+```
+
+### docker-build:compiled
+
+Команда `arui-scripts docker-build:compiled` во многом аналогична `docker-build`, но вместо сборки проекта использует уже скомпилированный в папку `.build` код.
+При этом в контейнер будут устанавливаться только production зависимости.
+Команду предполагается использовать в CI/CD, когда проект собирается в отдельном шаге и результат сборки уже доступен.
+За счет того, что в контейнер папки node_modules не копируются, а устанавливаются только production зависимости, скорость сборки контейнера значительно увеличивается.
+В процессе сборки так же будет модифицироваться файл `.dockerignore` для того чтобы гарантировано исключить папку `node_modules` из контекста сборки докера.
+
+`arui-scripts docker-build:compiled` имеет те же опции, что и `arui-scripts docker-build`.
+Dockerfile при этом будет сгенерирован автоматически, но вы можете переопределить его используя механизм [overrides](overrides.md).
+Локальный `Dockerfile` в корне проекта в данном случае полностью игнорируется.
+
+**Как запустить?**
+```bash
+arui-scripts docker-build:compiled
+```
+
+### archive-build
+
+Собирает архив с production сборкой.
+
+Этот вариант может быть полезен если вы хотите деплоить ваше приложение через подключение архива в марафоне.
+
+Команда предполагает наличие установленных `node_modules` перед сборкой, в процессе работы же очищает дев зависимости используя `yarn` или `npm`.
+yarn будет использоваться когда в рутовой папке проекта есть `yarn.lock` и `yarn` доступен в системе.
+Если вы используете yarn 2, для выполнения команды очистки используется плагин [workspace-tools](https://github.com/yarnpkg/berry/blob/HEAD/packages/plugin-workspace-tools/README.md), поэтому он должен быть установлен и указан в `.yarnrc.yml` вашего проекта.
+
+Итоговый архив будет содержать в себе `.build`, `node_modules`, `package.json` и `config` папки вашего проекта.
+
+**Как запустить?**
+```bash
+arui-scripts archive-build
+```
+
+### bundle-analyze
+
+Запускает [webpack-bundle-analyzer](https://www.npmjs.com/package/webpack-bundle-analyzer) для анализа размера бандлов.
+Так же при запуске будет генерироваться [stats-файл](https://webpack.js.org/api/stats/), который можно использовать в
+[сторонних](http://webpack.github.io/analyse/) инструментах, например для понимания почему тот или иной модуль попал в бандл.
+По умолчанию файл будет писаться в `.build/stats.json`, вы можете поменять это через отдельную [настройку statsOutputFilename](settings.md#statsOutputFilename).

package/docs/compilers.md

@@ -0,0 +1,18 @@
+## Конфигурация typescripts
+
+Компиляция TS работает из коробки, если в корне проекта есть файл `tsconfig.json`.
+За основу можно использовать дефолтный конфиг:
+
+```json
+{
+    "extends": "./node_modules/arui-scripts/tsconfig.json"
+}
+```
+
+По умолчанию TS будет компилироваться через babel, но у этого есть ряд ограничений:
+- нельзя использовать namespace
+- Нельзя использовать устаревший синтаксис import/export (`import foo = require(...)`, `export = foo`)
+- enum merging
+
+Если вы используете что-то из вышеперечисленного - вы можете вернуться к использованию tsc для компиляции ts файлов используя
+настройку [`useTscLoader`](settings.md#usetscloader).

package/docs/examples.md

@@ -0,0 +1,100 @@
+Примеры входных точек для сервера и клиента
+===
+
+## Клиент
+Для корректной работы hot-module-replacement на клиенте вам надо добавить примерно такой код:
+
+_./src/index.tsx_
+```tsx
+import React from 'react';
+import ReactDOM from 'react-dom';
+import { App } from './components/app';
+
+const targetElement = document.getElementById('react-app');
+
+ReactDOM.render(
+    <App />,
+    targetElement
+);
+
+if (process.env.NODE_ENV !== 'production' && module.hot) {
+    module.hot.accept('./components/app', () => {
+        let NextAppAssignments = require('./components/app').App;
+
+        ReactDOM.render(
+            <NextAppAssignments />,
+            targetElement
+        );
+    });
+}
+```
+
+## Сервер
+
+### Использование hot-module-replacement
+По умолчанию серверная часть приложения будет просто перезапускаться после каждого изменения кода,
+для использования hot module replacement на сервере можно использовать настройку [`useServerHMR`](settings.md#useserverhmr).
+
+Ваша входная точка сервера должна выглядеть примерно так (на примере hapi):
+
+_./src/server/index.ts_
+```ts
+import server from './server';
+
+let currentServer = server;
+
+async function startServer() {
+    try {
+        await currentServer.start();
+    } catch (error) {
+        console.error('Failed to start server', error);
+        process.exit(1);
+    }
+}
+
+startServer();
+
+if (module.hot) {
+    module.hot.accept(['./server'], async () => {
+        try {
+            await currentServer.stop();
+
+            currentServer = server; // импорт из сервера заменится самостоятельно
+            await startServer();
+        } catch (error) {
+            console.log('Failed to update server. You probably need to restart application', error);
+        }
+    });
+}
+```
+
+_./src/server/server.ts_
+```ts
+import hapi from 'hapi';
+const server = new hapi.Server();
+
+server.ext('onPostStart', (_, done) => {
+    console.log(`Server is running: ${server.info.uri}`);
+    done();
+});
+
+(async () => {
+    server.connection({ port: 3000 });
+
+    // ...
+    // конфигурация вашего сервера
+    // ...
+})();
+
+export default server;
+```
+
+Таким образом после изменения кода сервер не будет полностью пререзагружаться, что во многих случаях быстрее.
+В случае изменения входной точки сервера при использовании HMR вам надо будет перезапускать сервер вручную.
+
+### Формирование html для серверного рендеринга
+
+Для того чтобы корректно формировать html вам нужно знать имена чанков, которые будут сгенерированы вебпаком.
+Для этого рекомендуется использовать метод `readAssetsManifest` из `@alfalab/scripts-server`, который возвращает объект с именами чанков.
+
+Документация по `readAssetsManifest` доступна [здесь](../../arui-scripts-server/README.md#readassetsmanifest).

package/docs/overrides.md

@@ -0,0 +1,122 @@
+Тонкая настройка
+===
+
+Если вам не хватает гибкости при использовании `arui-scripts`, например вы хотите добавить свой плагин для вебпака -
+вы можете воспользоваться механизмом `overrides`.
+
+Для этого вам необходимо создать в корне вашего проекта файл `arui-scripts.overrides.js` или `arui-scripts.overrides.ts`, из которого вы сможете управлять
+конфигурацией почти всех инструментов, используемых в `arui-scripts`.
+
+Принцип работы тут следующий. Для всех конфигураций определен набор ключей, которые они будут искать в `arui-scripts.overrides.js`,
+В случае если такой ключ найден и это функция - она будет вызвана, и в качестве аргументов ей будут переданы
+существующая конфигурация и полный конфиг приложения (см [AppConfig](../src/configs/app-configs/types.ts)).
+Возвращать такая функция должна так же конфигурацию.
+
+Пример `arui-scripts.overrides.js`:
+```javascript
+const path = require('path');
+module.exports = {
+    webpack: (config, applicationConfig) => {
+        config.resolve.alias = {
+            components: path.resolve(__dirname, 'src/components')
+        };
+        return config;
+    }
+};
+```
+
+Пример `arui-scripts.overrides.ts`:
+```ts
+import type { OverrideFile } from 'arui-scripts';
+import path from 'path';
+
+const overrides: OverrideFile = {
+    webpack: (config, applicationConfig) => {
+        config.resolve.alias = {
+            components: path.resolve(__dirname, 'src/components')
+        };
+        return config;
+    }
+};
+
+export default overrides;
+```
+
+**В случае, если у вас на проекте лежит и ts, и js файл с overrides, использоваться будет js версия.**
+
+С помощью этой конфигурации ко всем настройкам вебпака будет добавлен `alias` *components*.
+
+На данный момент можно переопределять следующие конфигурации:
+- `babel-client` - конфигурация `babel` для клиентского кода. Ключи: `babel`, `babelClient`.
+- `babel-server` - конфигурация `babel` для серверноого кода. Ключи: `babel`, `babelServer`.
+- `dev-server` - конфигурация `webpack-dev-server`. Ключи: `devServer`.
+- `postcss` - конфигурация для `postcss`. Ключи: `postcss`.
+  > `config` postcss содержит массив с уже инициализированными плагинами, параметры которых уже зафиксированны. Если необходимо изменить параметры плагинов можно пересоздать конфиг, таким образом:
+    ```javascript
+    import {
+        createPostcssConfig, // функция для создания конфигурационного файла postcss
+        postcssPlugins, // список плагинов
+        postcssPluginsOptions, // коллекция конфигураций плагинов
+    } from 'arui-scripts/build/configs/postcss.config';
+
+    module.exports = {
+        postcss: (config) => {
+            const { files } = postcssPluginsOptions['@csstools/postcss-global-data'];
+            const newOption = {
+                ...postcssPluginsOptions,
+                '@csstools/postcss-global-data': {
+                    files:files.concat(['./vars.css'])
+                }
+            };
+            return createPostcssConfig(postcssPlugins, newOption);
+        },
+    };
+    ```
+- `stats-options` - конфигурация для [webpack-stats](https://webpack.js.org/configuration/stats/). Ключи: `stats`.
+- `webpack.client.dev` - конфигурация для клиентского webpack в dev режиме.
+  Ключи: `webpack`, `webpackClient`, `webpackDev`, `webpackClientDev`.
+- `webpack.client.prod` - конфигурация для клиентского webpack в prod режиме.
+  Ключи: `webpack`, `webpackClient`, `webpackProd`, `webpackClientProd`.
+- `webpack.server.dev` - конфигурация для серверного webpack в dev режиме.
+  Ключи: `webpack`, `webpackServer`, `webpackDev`, `webpackServerDev`.
+- `webpack.server.prod` - конфигурация для серверного webpack в prod режиме.
+  Ключи: `webpack`, `webpackServer`, `webpackProd`, `webpackServerProd`.
+- `supporting-browsers` - список поддерживаемых браузеров в формате [browserslist](https://github.com/browserslist/browserslist).
+  Ключи: `browsers`, `supportingBrowsers`
+- `Dockerfile` - докерфайл, который будет использоваться для сборки контейнера.
+  Базовый шаблон [тут](../src/templates/dockerfile.template.ts).
+  [`Dockerfile` в корне проекта](#docker) имеет приоритет над overrides.
+- `DockerfileCompiled` - докерфайл, который будет использоваться для сборки контейнера при использовании команды `arui-scripts docker-build:compiled`
+- `nginx` - шаблон конфигурации для nginx внутри контейнера.
+  Базовый шаблон [тут](../src/templates/nginx.conf.template.ts).
+  [Файл `nginx.conf`](nginx.md) в корне имеет приоритет над оверрайдами.
+- `start.sh` - шаблон entrypoint докер контейнера. Базовый шаблон [тут](../src/templates/start.template.ts).
+- `serverExternalsExemptions` - список модулей, которые не будут добавлены в список внешних зависимостей сервера. [Подробнее](caveats.md#node-externals).
+
+Для некоторых конфигураций определены несколько ключей, они будут применяться в том порядке, в котором они приведены в этом файле.
+
+### Создание дополнительных конфигураций для webpack
+На некоторых проектах может потребоваться создать дополнительные конфигурации для webpack. Например, для создания
+service worker'а (или любых других кейсов). Для этого можно использовать функцию-хелпер `createSingleWebpackConfig`:
+
+```ts
+import type { OverrideFile } from 'arui-scripts';
+
+const overrides: OverrideFile = {
+    webpackClient: (config, appConfig, { createSingleClientWebpackConfig }) => {
+        return [
+            config,
+            createSingleClientWebpackConfig(
+                './src/sw.js', // entrypoint, может быть массивом/объектом
+                'sw', // наименование сборки, влияет на имена чанков
+            ),
+        ];
+    }
+};
+
+export default overrides;
+```
+Эта функция вернет независимую конфигурацию для webpack, которую можно использовать в качестве оверрайда. Вы так же можете ее модифицировать,
+не боясь что это повлияет на другие конфигурации.
+
+Созданная таким образом конфигурация будет шарить с оригинальной конфигурацией только плагин для формирования assets-manifest'а.

package/docs/presets.md

@@ -0,0 +1,65 @@
+Пресеты
+===
+
+В случае, если вы хотите использовать определенный набор конфигураций и оверрайдов сразу в нескольких проектах - вам может
+помочь механизм пресетов. Он позволяет выносить конфигурацию и оверрайды в отдельный пакет.
+Для того чтобы использовать персеты на проекте вы должны указать в настройках проекта имя пакета с пресетами:
+
+```json
+{
+    "aruiScripts": {
+        "presets": "my-company-presets"
+    }
+}
+```
+
+Как пресет должен быть указан путь до папки с общими настройками (для поиска пути будет использоваться `require.resolve`
+от папки, содержащей package.json. Так что это может быть как папка в проекте, так и пакет из node_modules).
+
+Сам пакет с пресетами может содержать два файла:
+- `arui-scirpts.config.js` (или `arui-scripts.config.ts`)
+- `arui-scripts.overrides.js` (или `arui-scirpts.overrides.ts`)
+
+### arui-scripts.config (js | ts)
+С помощью этого файла можно задать любые ключи [конфигурации](settings.md).
+```js
+module.exports = {
+    baseDockerImage: 'my-company-artifactory.com/arui-scripts-base:11.2'
+};
+```
+
+Или в виде ts:
+```ts
+import type { PackageSettings } from 'arui-scripts';
+
+const settings: PackageSettings = {
+    baseDockerImage: 'my-company-artifactory.com/arui-scripts-base:11.2'
+};
+
+export default settings;
+```
+
+На проекте конфиурация будет загружаться в следующем порядке:
+1. базовые настройки из arui-scripts
+2. настройки из presets
+3. настройки из package.json проекта
+4. настройки, переданные через env переменную.
+
+**Важно!**
+
+Если вы будете задавать относительные пути через общие конфигурации (например `serverEntry`, `additionalBuildPath` и другие)
+они будут вычисляться относительно корня проекта, а не вашей конфигурации.
+Вы можете использовать абсолютные пути при необходимости задать путь до файла внутри пакета с пресетами.
+
+### arui-scripts.overrides (js | ts)
+С помощью этого файла можно задать базовые оверрайды проекта, аналогично [заданию оверрайдов на проекте](overrides.md).
+```js
+module.exports = {
+    babelClient(config) {
+        config.plugins.push('my-awesome-babel-plugin');
+        return config;
+    }
+};
+```
+
+На проекте оверрайды из пресетов будут выполняться в первую очередь, после них будут выполняться оверрайды из проекта.