Пользовательские шаблоны с приложением Create React

Шаблоны отличные. Они служат полезной отправной точкой для проектов и могут сократить общую работу по настройке и настройке. Мы также можем улучшить их с помощью инструментов, которые по умолчанию продвигают хорошие привычки и процессы, что упрощает принятие «правильных» решений. Это экономит время и мыслительные ресурсы - избавившись от этих задач, у вас будет больше времени, чтобы сосредоточиться на написании кода.

Со временем шаблоны можно расширять и уточнять. Опираясь на то, что у нас уже есть, мы можем начинать все дальше и дальше с «нуля». На мой взгляд, это резюмирует процесс технического прогресса: упаковывая что-то полезное и облегчая копирование, мы можем направить наши усилия на решение «следующей» проблемы.

Так что да, если вы еще не догадались, я большой поклонник шаблонов. В этом посте будет рассмотрен процесс создания настраиваемого шаблона для Create React App (CRA), используя официальный шаблон по умолчанию в качестве основы.

Планирование шаблона

У шаблонов любого типа должна быть четкая цель. Это помогает избежать ситуации, когда мы в конечном итоге используем слишком много возможностей и сталкиваемся с трудными решениями о том, что следует и не следует включать. В конце концов, мы стараемся облегчить себе жизнь!

Мы собираемся рассмотреть более общий базовый вариант использования, поэтому он будет легким с некоторыми утилитами, которые будут полезны для любого проекта. Если бы у вас был более конкретный вариант использования, имело бы смысл создать более специализированный шаблон с функциями и утилитами, относящимися к проблемной области.

Что мы будем делать:

использовать официальный шаблон CRA по умолчанию в качестве отправной точки
удалить некоторые файлы
обновить некоторые файлы
добавить некоторые общие утилиты (Prettier, Source Map Explorer, отчеты о тестировании покрытия с помощью Jest)
протестируйте это, создав новый проект

Анатомия шаблона CRA

Шаблон CRA состоит из двух ключевых элементов:

/template

может содержать все, что вы хотите, и составит основу вашего вновь созданного проекта
должен содержать как минимум несколько общих файлов и папок, чтобы react-scripts работал должным образом

template.json

файл конфигурации для вашего шаблона
в настоящее время поддерживает единственный ключ, "package", под которым вы можете вложить информацию, которая будет объединена в package.json файл только что созданного проекта
любые зависимости и сценарии, которые вы укажете, будут объединены со значениями по умолчанию в react-scripts (т.е. зависимости, такие как сам React, и сценарии, которые настраивают ваше приложение для разработки / сборки)
другие значения будут просто скопированы напрямую, заменив любые значения по умолчанию, если они уже существуют

Шаблон должен иметь как минимум следующую структуру и файлы, как указано в Документации CRA:

README.md
template.json
package.json
template/
  README.md
  gitignore (renamed to .gitignore during the init process)
  public/
    index.html
  src/
    index.js

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

Чтобы гарантировать соответствие минимальным критериям, указанным выше, мы можем использовать официальный шаблон по умолчанию CRA в качестве основы для нашего собственного шаблона.

В своем терминале перейдите в каталог, в котором должен находиться этот шаблон, и выполните следующие команды:

# Clone the repo
git clone https://github.com/facebook/create-react-app.git
# Copy the template into the current directory
cp -r create-react-app/packages/cra-template .
# Clean up after ourselves
rm -rf create-react-app

Убираться

Давайте избавимся от некоторых ненужных файлов и отредактируем несколько из существующих, чтобы у нас осталось только то, что нам нужно.

1. Удалите App.css и logo.svg из каталога /template.

2. Обновите App.js:

import React from 'react';
const App = () => <h1>Hello, world</h1>;
export default App;

3. Обновите App.test.js, чтобы отразить изменение на <App />:

test('renders test heading', () => {
  render(<App />);
  const headingElement = screen.getByText(/hello, world/i);
  expect(headingElement).toBeInTheDocument();
});```

4. Последний шаг - добавить в ваш package.json следующее:

{
  ...
  "main": "template.json"
}

N.B. это необходимый шаг до выпуска CRA v4. Исправление уже сделано.

Вы также можете обновить имя и информацию в README.md и package.json, а также имя каталога, в котором мы работаем, но я оставлю это на ваше усмотрение.

Добавление некоторых общих утилит

Есть несколько вещей, которые я всегда настраиваю в новых проектах - этот шаблон - идеальное место для размещения этих вещей.

Мы собираемся добавить:

Красивее, чтобы код оставался хорошо отформатированным.
Source Map Explorer, чтобы мы могли следить за состоянием пакета приложения.
скрипт npm для отчета о покрытии кода с помощью Jest

Примечание об указании зависимостей

Нам нужно будет добавить несколько зависимостей, чтобы выполнить следующие шаги. На самом деле мы не собираемся их устанавливать, нам просто нужно указать, что нам нужно в template.json, чтобы CRA знал, что устанавливать, когда мы используем этот шаблон для создания нового проекта. Для этого мы воспользуемся следующим процессом:

перейти на сайт npm
найдите пакет, который нужно добавить
скопируйте номер версии, а затем добавьте пакет и номер версии в template.json с ^ в качестве префикса, например:

{
  "package": {
    "dependencies": {
      "prettier": "^2.0.5"
    }
  }
}

Символ ^ - это каретка, которая позволяет нам дать npm разрешение на установку более новых минорных версий пакета или версий с исправлениями - это все равно что сказать: Не стесняйтесь устанавливать более новую версию, если она есть, но без критических изменений, пожалуйста. Он действительно полагается на то, что авторы пакета следуют семантическому управлению версиями, но большинство крупных проектов с открытым исходным кодом делают это, поэтому мы должны быть в порядке, просто помните об этом. Это будет означать, что мы можем работать в течение более длительного периода времени без необходимости обновлять зависимости шаблона (хотя это то, что нужно периодически пересматривать, чтобы мы могли извлечь выгоду из последних выпусков). Если вам нужна конкретная версия пакета, вы можете отключить это.

N.B. в то время как вы обычно добавляете их как devDependencies, текущая система шаблонов в CRA поддерживает только перечисление их как обычных dependencies. Хотя это не считалось проблемой в прошлом, теперь похоже, что это будет поддерживаться в следующем выпуске.

Добавление красивее

Мы собираемся добавить Prettier и запустить его с хук pre-commit, используя Husky.

1. Добавьте prettier, pretty-quick и husky к dependencies в template.json

2. Создайте файл с именем prettier.config.js в /template и добавьте параметры конфигурации:

// Some of these are defaults, but let's be explicit for other humans
module.exports = {
  tabWidth: 2,
  semi: true,
  singleQuote: true,
  bracketSpacing: true,
  printWidth: 80,
};

3. Создайте файл с именем .prettierignore в /template (пока он может оставаться пустым).

4. Создайте файл с именем husky.config.js в /template и добавьте следующее:

module.exports = {
  hooks: {
    'pre-commit': 'npm run pre-commit',
  },
};

5. В template.json добавьте объект "scripts" в "package" с помощью следующего скрипта:

{
  "package": {
    ...
    "scripts": {
      "pre-commit": "pretty-quick --staged"
    }
  }
}

N.B. вы также можете добавить Prettier в фактический шаблон CRA, который мы создаем, чтобы код вашего шаблона также был отформатирован.

Добавление обозревателя исходной карты

Возможность видеть, что на самом деле входит в ваши пакеты, полезна при попытке уменьшить размер пакета и уберечь пользователя от загрузки ненужных байтов. Чтобы получить некоторое представление об этом, мы собираемся использовать Source Map Explorer.

1. Добавьте source-map-explorer в dependencies в template.json

2. В template.json добавьте к объекту "scripts" следующее:

{
  "package": {
    ...
    "scripts": {
      ...
      "analyze": "source-map-explorer 'build/static/js/*.js'"
    }
  }
}

Вот и все! Эта команда будет смотреть только на созданные файлы. При желании можно указать префикс команды над npm run build &&, чтобы не создавать отдельный шаг перед выполнением этой команды.

Добавление отчетов о покрытии кода с помощью Jest

Это тоже довольно просто. У Jest есть собственная встроенная функция создания отчетов о покрытии, а сам пакет уже поставляется с любым приложением, созданным с использованием CRA, поэтому нам даже не нужно добавлять какие-либо зависимости.

В template.json добавьте к объекту "scripts" следующее:

{
  "package": {
    ...
    "scripts": {
      ...
      "coverage": "npm test -- --coverage --watchAll=false"
    }
  }
}

Собираем все вместе

Теперь, когда мы добавили кучу полезных вещей, нам нужно убедиться, что все работает должным образом. CRA позволяет указать путь к настраиваемому шаблону при создании нового приложения. Для удобства вы можете добавить в свой .bash_profile что-то вроде этого:

# Maybe with a catchier name...
alias create-react-app-custom="npx create-react-app --template=file:/path/to/template"

Подсказка: быстрый способ убедиться, что вы получили правильный путь, - это ввести use pwd в свой терминал и просто скопировать / вставить результат в псевдоним выше.

Теперь вы можете просто запускать следующее каждый раз, когда захотите использовать этот шаблон:

create-react-app-custom <name> [options]

N.B. вам нужно будет открыть новое окно терминала, чтобы это изменение в вашем .bash_profile вступило в силу.

В новом окне терминала попробуйте запустить следующую команду и посмотреть на вывод:

create-react-app-custom custom-app

Содержание созданного проекта должно быть вам знакомо. Это содержимое /template, и если вы посмотрите package.json для этого проекта, вы увидите, что зависимости и сценарии, которые мы указали в template.json, были включены.

Чтобы проверить правильность добавления наших дополнений, вы можете сделать следующее:

Prettier: испортите форматирование и зафиксируйте изменение, чтобы увидеть, как обработчик предварительной фиксации прибрался для вас (например, удалите точки с запятой в App.js)
Обозреватель исходных карт: запустите npm run build && npm run analyze, чтобы просмотреть отчет в браузере.
Покрытие теста: запустите npm run coverage, чтобы просмотреть очень простой отчет о покрытии на основе <App> теста по умолчанию, который мы оставили в

Когда команда тестового покрытия запускается, она также создает новую папку /coverage. Вы можете открыть ./coverage/lcov-report/index.html в своем браузере для более интерактивного взаимодействия. N.B. в вашем терминале могут появиться ошибки, связанные с этой проблемой, но папка /coverage все равно должна быть создана.

Вот и все, что касается базового шаблона! При использовании этого шаблона для создания новых проектов нам больше не нужно удалять стандартные файлы, которые нам не нужны, и несколько полезных утилит настроены прямо из коробки.

Следующие шаги

Если вы еще не были проданы, я надеюсь, что в процессе чтения вы поняли, что шаблоны могут быть невероятно полезными. Мы добавили несколько основных инструментов повышения качества жизни для новых проектов, в которых используется этот шаблон, но есть множество других вещей, которые вы можете добавить в зависимости от вашего варианта использования, и это лишь некоторые из них:

настройте предпочтительное решение для стилизации с помощью базовой темы, глобальных стилей по умолчанию (размер коробки кто-нибудь?)
Плагины react-axe и a11y
изменить значки и HTML по умолчанию в /public
i18n конфигурация
предпочтительная структура папок
добавить больше сценариев npm, соответствующих вашим обычным рабочим процессам
общие пакеты, которые вы всегда используете, включая ваши собственные утилиты

Подведение итогов

Мы рассмотрели возможность создания собственного настраиваемого шаблона для приложения Create React, взяв за основу официальный стартер. Это было так же просто, как удаление нежелательного кода и файлов, указание некоторых пакетов и сценариев для включения в новые проекты и их тестирование.

Наконец, вы должны помнить, что, хотя шаблоны могут помочь нам сэкономить время и избавиться от повторяющихся задач, важно подумать о вашем сценарии использования и о том, что включить. Если вы регулярно попадаете в ситуацию, когда вы редактируете или удаляете файлы и утилиты, созданные с помощью вашего шаблона, вы, вероятно, немного перестарались.

Эта запись изначально была опубликована на tomvalorsa.com