Публикация NPM-пакетов / Habr

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

1. Создание проекта

Я предпочитаю по возможности брать готовые инструменты, а не изобретать велосипед. Поэтому использую стандартный Create React App. Для поднятия проекта, который будет написан на TypeScript, следует использовать команду:

npx create-react-app my-app --template typescript

Созданный проект будет полностью сконфигурирован для работы с TypeScript.

2. Подготовка структуры проекта

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

src
  App.css
  App.tsx
  index.css
  index.tsx

Файлы react-app-env.d.ts, reportWebVitals.ts и setupTests.ts не трогаю.

Файлы библиотеки расположим в каталоге src/lib, структура которого будет следующей:

src
  lib
   components
   tests
   index.css
   index.ts

Тут все очевидно: компоненты располагаем в components, тесты в tests, точка входа в библиотеку будет в index.ts, стили в index.css.

3. Подготовка package.json

Из коробки Create React App создает минималистичный package.json. Для публикации его необходимо дополнить:

name - указать реальное название пакета (а не название приложения). Мне лень искать адекватное название в общем пространстве имен, поэтому я использую собственный скоп: @alxgrn/react-form.
description - описание.
private - надо поставить в false.
author - укажем автора, пусть все знают!
license - указать лицензию. Я выбрал Apache-2.0. Название надо указывать в правильном формате, если сомневаетесь, потренируйтесь с использованием команды npm init, она умеет проверять.
keywords - массив ключевых слов для облегчения поиска пакета.
main и module - точка входа в библиотеку. Мы будем располагать готовые файлы в каталоге dist с точкой входа dist/index.js. Надо отметить что поле module отсутствует в документации, но повсеместно используется. Зачем оно нужно при наличии main - загадка, которую лень разгадывать, поэтому просто напишем и все.
files - массив файлов, которые будем публиковать. Мы указываем каталог dist, куда сложим готовый проект. По умолчанию также будут добавлены README и LICENSE, причем с любыми расширениями и регистром.
homepage, repository, bugs - тут все понятно.

ВАЖНО: После того как вы укажете в homepage что-то типа:

"homepage": "https://github.com/alxgrn/react-form#readme",

Ваше тестовое приложение перестанет работать т.к. после сборки будет искать файлы проекта хрен знает где. Для фикса этой неприятности необходимо подправить в секции scripts запуск команды start следующим образом:

"start": "PUBLIC_URL=/ react-scripts start",

4. Установка и настройка babel

Обидно осознавать что Create React App умеет делать все, что нам надо для сборки проекта, но делает это где-то у себя внутри по своим правилам, в которые нас не особо посвящает. Было бы здорово, если бы он умел сразу готовить проект к публикации, но нет, так нет. Будем сами.

Для преобразования TypeScript в JavaScript, который затем перегоним в "древний" JavaScript мы будем использовать babel. Установим его в проект:

npm install --save-dev @babel/cli @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript

Сконфигурируем babel создав в корне файл babel.config.json с следующим содержанием:

{
    "comments": false,
    "presets": [
        [
            "@babel/preset-env",
                {
                    "targets": "> 0.25%, not dead",
                    "useBuiltIns": "usage",
                    "corejs": "3.6.5"
                }
        ],
        "@babel/preset-react",
        "@babel/preset-typescript"
    ],
    "ignore": [
        "**/tests",
        "**/*.d.ts"
    ]
}

Мы удаляем из результата комментарии, игнорируем файлы тестов (которые будем держать в каталоге src/lib/tests) и объявления типов (о которых ниже).

Теперь добавим в раздел scripts в файле package.json команду для запуска билда:

"build:js": "rm -rf dist && NODE_ENV=production babel src/lib --out-dir dist --copy-files --extensions \".ts,.tsx\" --source-maps true"

Как уже отмечалось ранее, мы будем складывать результат сборки в каталог dist в корне проекта. Поэтому первое что делает этот скрипт - удаляет предыдущую сборку. Затем он устанавливает переменную среды окружения в продакшен режим и запускает babel. Babel будет искать для обработки файлы с расширениями .ts,.tsx (кроме тех что указали в блоке ignore в файле конфигурации) в каталоге src/lib, а результат записывать в каталог dist. Необработанные файлы будут просто скопированы в dist. Также будут созданы файлы с sourcemap.

5. Генерация файлов объявления типов

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

На предыдущем шаге мы уже сказали babel не обрабатывать эти файлы, а просто скопировать в папку dist. Теперь осталось их сгенерировать. Так как мы использовали Create React App у нас уже есть компилятор tsc, поэтому просто воспользуемся им. Добавим в раздел scripts файла package.json следующую команду:

"build:types": "./node_modules/.bin/tsc --project ./tsconfig.types.json",

Обратите внимание на то, что мы указываем компилятору использовать файл проекта tsconfig.types.json. Мы не можем использовать файл tsconfig.json, который для нас создал Create React App т.к. в нем установлен флаг noEmit, который не совместим с нужным нам флагом emitDeclarationOnly.

Поэтому мы просто копируем файл tsconfig.json в tsconfig.types.json, затем в блоке compilerOptions добавляем "declaration":true и "emitDeclarationOnly": true, а "noEmit": true, наоборот, убираем.

Дополнительно мы меняем в блоке include каталог на src/lib, так как нас интересует только он.

Теперь при запуске команды

npm run build:types

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

6. Добавим команду сборки

Для создания дистрибутива нам нужно сначала сгенерировать файлы деклараций, а затем запустить babel. Для удобства добавим в раздел scripts в файле package.json команду, которая все это сотворит:

"build:dist": "npm run build:types && npm run build:js && rm -rf dist/tests",

Дополнительно добавили удаление каталога tests из дистрибутива, т.к. вряд ли он там нужен.

7. Работа с зависимостями

Вернемся к файлу package.json. В нем присутствуют две секции dependencies и devDependencies. В первом перечислены зависимости, которые требуются для работы пакета в продакшене, во втором - только во время разработки.

Это все прекрасно пока мы создаем приложение, но когда мы пишем библиотеку, мы должны учитывать что она будет помещена в целевой проект. В нем скорее всего уже будут установлены зависимости, которые мы тоже используем. Уж точно там будет установлен react коль скоро мы пишем библиотеку react-компонентов. Не обязательно, но возможно, что и другие компоненты тоже уже будут установлены. Если мы оставим эти зависимости внутри своего dependencies, могут возникнуть всякие неприятности типа использования двух реактов в одном приложении. Нам такое не надо. Поэтому я перенес все зависимости из dependencies в devDependencies, а те, которые нам нужны для продакшена в peerDependencies:

"peerDependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-children-utilities": "^2.8.0"
}

Как видите, помимо реакта мне нужен пакет react-children-utilities.

После этих изменений полезно будет запустить

npm install

8. Публикация пакета

Теперь все готово к публикации пакета. Но есть несколько нюансов.

8.1. Я решил использовать в названии пакета имя своего аккаунта т.е. в терминологии npm у меня scoped package. По умолчанию такие пакеты считаются приватными и для их публикации в первый раз надо использовать специальный флаг:

npm publish --access public

В дальнейшем можно запускать команду без этого флага.

8.2. Прежде чем реально публиковать пакет, неплохо было бы его протестировать. Для этого можно использовать команду "npm link". Но надо быть готовым к тому что всплывет ошибка связанная с Duplicate React.

8.3. Перед очередной публикацией необходимо изменить версию пакета. Можно это делать руками, а можно использовать команду "npm version".

9. Плюшки

После публикации захочется плюшек.

9.1. Покрытие тестами

Чтобы coverage тестов считался только в каталоге библиотеки, надо добавить в pakage.json настройку для jest:

"jest": {
    "collectCoverageFrom": [
        "src/lib/**/*.{js,jsx,ts,tsx}"
    ]
}

9.2. Беджики в README.md

Беджиков много, их почему-то все любят. Брать можно на shields.io. Для текущей версии и типа лицензии можно взять сразу.

Для беджика прохождения билда можно настроить Action "Node.js CI" на GitHub. В неё же можно сразу добавить интеграцию с codecov.io для вывода беджика покрытия тестами. Codecov, в отличии от Travis CI, не просит вводить данные карты для открытых проектов.

10. Вот и всё

Надеюсь кому-то будет полезно.