Rearguard

Содержание

Мотивация
Установка
CLI
Использование
Конфигурация
Минимально необходимая структура проекта
Пример работы modules
Пример работы proxy
Что внутри?

Мотивация:

Версионирование конфигурации сборки;
Простота разворачивания конфигурации сборки определённой версии;
Инкрементные обновления rearguard;
Легкость обновления на нескольких проектах;
Устранение избыточности в виде копий сборки в каждом проекте;
Возможность устанавливать rearguard глобально;
Одна единственная зависимость в package.json для разработки;
Быстрый старт проекта без необходимости настройки;
Тестирование конфигурации и корректной сборки проекта.
Получить минимально доступную гибкость (подключение плагинов для PostCSS и Babel);
Минималистичный конфигурационный файл;
Проверка конфигурации на избыточные, недостающие или некорректные свойства. Имеется в виду build.config.json. Он содержит полный список полей доступных для конфигурации. Если указать неизвестные для rearguard поля, вы получите сообщение о том что они не используются. Если забыть указать необходимое поле, применится значение по умолчанию и получите сообщение о произошедшем. Если указать неправильный тип данных для поля, то вы также получите оповещение о том какие настройки в него применились.

Установка

npm install -g rearguard

если глобальная установка неподходит

npm install -D rearguard

CLI

rearguard [react | infernojs] [start | build]

Доступные флаги:

--typescript | -ts - включает поддержку typescript, ts, tsx файлов.
--isomorphic | -i - переводит сборку в изоморфный режим.
--onlyServer - работает только с серверной частью изоморфного приложения, фактически получается классический веб сервер где шаблонизатор это React или Infernojs.
--release | -r - сборка будет работать в production режиме как для start так и для build.
--analyze | -a - запустит webpack-bundle-analyzer, позволяет понять что участвует в сборке, нет ли лишнего или все ли необходимое подключилось.
--verbose | -v - делает вывод многословным.
--debug | -d - выведет дополнительную отладочную информацию.

Использование

Запуск SPA приложения основанного на библиотеке React

rearguard react start

Сборка в production режиме SPA приложения основанного на библиотеке React

rearguard react build --release

Запуск SPA приложения основанного на библиотеке infernojs

rearguard infernojs start

Сборка в production режиме SPA приложения основанного на библиотеке infernojs

rearguard infernojs build --release

Конфигурация

При первом запуске будет автоматически сгенерированно два файла в текущей директории

build.config.json - версионируется
socket.config.json - не версионируется

build.config.json:

{
  "context": "src",
  "entry": "index.jsx",
  "output": {
    "path": "dist",
    "publicPath": "/"
  },
  "modules": [
    "src"
  ],
  "browserslist": [
    ">0.1%",
    "last 2 versions",
    "not ie <= 11"
  ],
  "proxy": {
    "/graphql": "http://localhost:9000",
    "/auth": "http://localhost:9000"
  },
  "isomorphic": {
    "entry": "server.jsx",
    "publicDirName": "public"
  },
  "css": {
    "isolation": true,
    "reset": {
      "all": "initial",
      "font-size": "inherit",
      "font-family": "Avenir Next, BlinkMacSystemFonts, Segoe UI, Roboto, Oxygen, Ubuntu, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif",
      "display": "block",
      "boxSizing": "border-box",
      "cursor": "inherit"
    },
    "postCssPlugins": "postCssPlugins.js"
  },
  "typescript": {
    "configPath": "tsconfig.json",
    "showConfigForIDE": true,
    "config": {
      "compilerOptions": {},
      "compileOnSave": false
    }
  }
}

socket.config.json:
```json
{
  "socket": {
    "port": "5000",
    "host": "localhost"
  }
}

postCssPlugins.js

module.exports = [
  require('postcss-nesting')(),
  require('postcss-nested')(),
  require('postcss-calc')(),
  require('postcss-extend')()
]

context - директория от которой будут расчитываться все остальные пути, можно указать путь внутри директории запуска.
entry - точка входа в приложение, указывается относительно context.
output.path - директория куда будут выгружен результат сборки.
output.publicPath - это url по которому можно будет получить статику.
modules - это директории в которых webpack будет искать модули, пример будет ниже.
browserslist - список который очерчивает круг поддерживаемых браузеров, используется для env и autoprefixer
proxy - объект отписывает с кого path перенаправлять на какой host и path, примеры будут ниже.
css.isolation - включают postcss-autoreset и postcss-initial
css.reset - настройки для postcss-autoreset и postcss-initial
css.postCssPlugins - путь к файлу postCssPlugins.js где подключаются плагины для PostCSS в целевом проекте.
typescript.configPath - путь к файлу tsconfig.json где находится конфигурация для typescript, этот файл конфигурации генерируется автоматически и нужен для того чтобы его читала IDE. Этот файл не версионируется.
typescript.showConfigForIDE - флаг необходимый для включения или выглючения генерации tsconfig.json файла. Если он не нужен то его можно и не генерировать.
typescript.config - объект с настройками компиляции TS, значия в этом объекте будут Object.assign с базовой конфигурацией, таким образом можно влиять на настройки TS.

Минимально необходимая структура проекта

SPA

my-app
├── package.json
├── public
│   └── favicon.ico
└── src
    └── index.jsx - точка входа в SPA приложение

Isomorphic

my-app
├── package.json
├── public
│   └── favicon.ico
└── src
    └── index.jsx - точка входа в SPA приложение
    └── server.jsx - точка входа в серверную часть приложения, тут веб сервер рендерит SPA.

Дальнейшее развитие проекта остается на усмотрение разработчика.

Пример работы modules

my-app
├── package.json
├── public
│   └── favicon.ico
└── src
    ├── outSideProjectFromGitSubmodule
    │   ├── package.json
    │   ├── public
    │   │   └── favicon.ico
    │   └── src
    │       ├── components
    │       │   ├── Component3.jsx      
    │       │   └── Component4.jsx 
    │       ├── export.jsx
    │       └── index.jsx
    ├── components
    │   ├── Component1.jsx    
    │   └── Component2.jsx      
    └── index.jsx

export.jsx

export {default as Component3} from 'components/Component3'
export {default as Component4} from 'components/Component4'

Если использовать так:

{
  "modules": [
    "src"
  ]
}

То чтобы получить export.jsx необходимо в файле Component2.jsx написать следующий импорт.

import { Component3 } from 'outSideProjectFromGitSubmodule/src/export'

Или получить Component4 без использования export.jsx

import Component4 from 'outSideProjectFromGitSubmodule/src/components/Component4'

Если добавить новую директорию для обнаружения компонентов

{
  "modules": [
    "src",
    "src/outSideProjectFromGitSubmodule/src"
  ]
}

То чтобы получить export.jsx необходимо в файле Component2.jsx написать следующий импорт.

import { Component3 } from 'export'

Или получить Component4 без использования export.jsx

import Component4  from 'components/Component4'

Или даже так

{
  "modules": [
    "src",
    "src/outSideProjectFromGitSubmodule/src",
    "src/outSideProjectFromGitSubmodule/src/components"
  ]
}

И получить Component4 по одному только имени

import Component4  from 'Component4'

Пример работы proxy

{
  "proxy": {
    "/graphql": "http://localhost:9000",
    "/auth": "http://localhost:9000"
  }
}

Все запросы начинающиеся на /graphql будут перенаправлениы на:

/graphql -> http://localhost:9000 /graphql
/graphql/data -> http://localhost:9000 /graphql/data

Все запросы начинающиеся на /auth будут перенаправлениы на:

/auth -> http://localhost:9000 /auth
/auth/user -> http://localhost:9000 /auth/user

KasperGreen/rearguard