Как создать пакет npm с помощью автоматизированного рабочего процесса

Недавно я опубликовал пакет npm. Это не первый пакет в моей жизни, но в этот раз он получился «настоящим»: два других пакета, которые я делал до этого, не были достаточно профессиональными, особенно с точки зрения DX — Developer Experience. Какие изменения я сделал?

Принудительное следование Conventional Commits для моих сообщений git-коммитов, используя Commitizen,
Использовал semantic-release и Github Actions для автоматического создания версий и релизов.
Использовал lint-staged для линтинга моих Javascript файлов перед каждым коммитом.
Добавление эмодзи в мои сообщения о фиксации

В этой статье я собираюсь поделиться с вами тем, чему я научился, и помочь вам начать работу с аналогичной установкой для вашего собственного пакета npm (или просто любого личного проекта, в общем).

Содержание

Конечная цель
Внимание!
Шаг 0 — Настройка проекта
Шаг 1 — Установка зависимостей
Шаг 2 — Настройка коммитов
ПРИМЕЧАНИЕ
Шаг 3 — Настройка автоматических релизов npm и Github
Шаг 4 — Добавьте красивый README

Конечная цель

Как именно эта настройка повлияет на ваш рабочий процесс? Давайте посмотрим:

Каждый раз, когда вы делаете git-коммит, в вашем терминале будет появляться подсказка GUI-in-CLI, которая поможет вам сделать обычный коммит, без необходимости запоминать формат таких коммитов.
В сообщение о фиксации также будет добавлен соответствующий emoji, в зависимости от типа сообщения.
Каждый раз, когда вы размещаете код в основной ветке вашего удаленного проекта, в зависимости от коммитов с момента последнего размещения, автоматически создается релиз npm, релиз Github и тег git! Все в соответствии с семантическим версионированием
Changelogs для отдельных релизов также будут автоматически опубликованы.

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

Внимание!

Если вы не хотите делать всю работу, вы можете воспользоваться этим пакетом, который я сделал, и который поможет вам быстро начать работу. Ознакомьтесь с readme для получения инструкций по установке и настройке, и поставьте звездочку, если вам понравилось!

Давайте начнем!

Шаг 0 — Настройка проекта

Начните с создания проекта Node.js. cd в папку с проектом и запустите npm init. Ответьте на появившиеся подсказки.

Также инициализируйте пустой git-репо и добавьте Github-репо в качестве удаленного.

Обязательно установите версию вашего пакета 0.0.0-development как индикатор для тех, кто смотрит на ваш код, что ваши релизы и номера версий автоматически управляются для вас.

Шаг 1 — Установка зависимостей

Нам понадобится довольно много зависимостей для нашей установки. Давайте установим их все одним махом. Добавьте следующие зависимости для разработки в ваш package.json:

"devDependencies": {
    "@commitlint/cli": "^17.0.3",
    "@commitlint/config-conventional": "^17.0.3",
    "cz-conventional-changelog": "3.3.0",
    "eslint": "^8.20.0",
    "husky": "^8.0.1",
    "lint-staged": "^13.0.3",
    "semantic-commit-emoji": "^0.6.2",
    "semantic-release": "^19.0.3",
    "semantic-release-gitmoji": "^1.4.4"
  }

Войти в полноэкранный режим Выйти из полноэкранного режима

А теперь запустите npm install, чтобы установить их все.

Шаг 2 — Настройка коммитов

Для настройки коммитов нам понадобятся такие инструменты, как Husky, Commitizen, commitlint и semantic-commit-emoji.

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

Husky — это инструмент, который упрощает работу с крючками Git. Код для хуков Husky задается в специальных файлах в папке .husky в корне проекта. Чтобы создать папку .husky, выполните команду npx husky install.

Запустите npx husky add .husky/commit-msg в корне проекта, чтобы создать хук, изменяющий сообщение о фиксации. Это создаст файл оболочки commit-msg в папке .husky. Поместите в этот shell-файл следующее:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx --no -- commitlint --edit $1
npx --no -s semantic-commit-emoji $1

Войти в полноэкранный режим Выйти из полноэкранного режима

Добавьте commitlint.config.cjs в корневой каталог и добавьте следующее содержимое:

const Configuration = {
  extends: ["@commitlint/config-conventional"],
  formatter: "@commitlint/format",
  ignores: [(commit) => commit === ""],
  defaultIgnores: true,
  helpUrl:
    "https://github.com/conventional-changelog/commitlint/#what-is-commitlint",
};

module.exports = Configuration;

Войти в полноэкранный режим Выйти из полноэкранного режима

Запустите npx husky add .husky/pre-commit для генерации еще одного хука (который, как следует из названия, запускается непосредственно перед pre-commit) и в сгенерированном shell-файле напишите:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx --no lint-staged

Войти в полноэкранный режим Выйти из полноэкранного режима

Это прикажет Husky отлинковать все наши staged файлы и внести все необходимые изменения.

Добавьте следующее в ваш package.json, чтобы указать файлы для линтинга:

"lint-staged": {
    "*.(js|ts|jsx|tsx)": "eslint"
}

Войти в полноэкранный режим Выйти из полноэкранного режима

Нам также нужно указать конфигурацию для eslint. Добавьте следующее в ваш package.json:

"eslintConfig": {
    "extends": "eslint:recommended",
    "env": {
      "browser": true,
      "node": true,
      "jest": true
    }
  }

Войти в полноэкранный режим Выйти из полноэкранного режима

Если вы используете для тестирования не Jest, внесите соответствующие изменения, а если вы используете Jest, убедитесь, что его зависимости тоже загружены и настроены должным образом: установите @babel/core, @babel/preset-env, babel-jest и jest в качестве зависимостей разработки, и создайте babel. config.cjs в корне вашего пакета со следующим содержимым:

module.exports = {
  presets: [["@babel/preset-env", { targets: { node: "current" } }]],
};

Войти в полноэкранный режим Выйти из полноэкранного режима

Если eslint не дает вам покоя за использование некоторых последних возможностей Javascript, вы можете добавить следующее к объекту eslintConfig выше:

"parserOptions": {
  "ecmaVersion": "latest"
}

Войти в полноэкранный режим Выйти из полноэкранного режима

Если ваш пакет имеет тип модуля (т.е. вы используете более сложные утверждения import вместо require), вам также нужно добавить "sourceType": "module" к этому объекту parserOptions. В зависимости от ваших требований (возможно, JSX, шаблоны Vue и т.д.), вы можете захотеть дополнительно настроить эту конфигурацию eslint.

Чтобы настроить Commitizen, добавьте следующее в ваш package.json:

"config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog"
    }
}

Войти в полноэкранный режим Выйти из полноэкранного режима

ПРИМЕЧАНИЕ

Теперь, когда вы настроили Commitizen, вы должны использовать git cz или cz вместо git commit, чтобы воспользоваться им.

Шаг 3 — Настройка автоматических релизов npm и Github

Создайте каталог .github в корне вашего проекта. Внутри создайте подкаталог workflows и добавьте файл .yml с любым именем, которое вы хотите (например, publish.yml). Добавьте в этот файл следующее содержимое:

name: Package release and publish
on:
  push:
    branches:
      - main
env:
  GH_TOKEN: ${{ secrets.GH_TOKEN }}
  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [16.x]
    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
          cache: "npm"
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test -- --watch=false --browsers=ChromeHeadless
      - run: npx semantic-release

Войти в полноэкранный режим Выйти из полноэкранного режима

Это укажет Github выполнять некоторые проверки каждый раз, когда вы делаете push в основную ветку вашего репозитория Github. Он выполнит ваши тесты и выпустит новый релиз на Github и npm. Но это еще не работает!

Сначала нам нужно сделать несколько секретов репо. Вот хорошее руководство от Azure, объясняющее, как это сделать. Это совсем не сложно.

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

GH_TOKEN — Он должен содержать токен персонального доступа Github. Вот как вы можете его создать. Убедитесь, что он достаточно разрешительный (если вы не уверены, можно поставить все галочки).
NPM_TOKEN — Этот параметр должен содержать токен автоматизации npm. Ознакомьтесь с этим руководством, чтобы узнать, как его сделать.

Мы почти у цели! Нам осталось настроить semantic-release, чтобы он работал так, как мы задумали. В ваш package.json добавьте следующее:

"release": {
    "branches": [
      "main"
    ],
    "plugins": [
      "semantic-release-gitmoji",
      "@semantic-release/npm",
      "@semantic-release/github"
    ]
},

Войти в полноэкранный режим Выйти из полноэкранного режима

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

Шаг 4 — Добавьте красивый README

Создайте красивый README.md с помощью readme.so и добавьте его в свой проект.

Вуаля! Мы закончили. Надеюсь, вы нашли этот пост полезным.
Проверьте пакет npm-pkg-gen, если хотите быстро начать работу, и опубликуйте его на Github, если он вам понравился!

До скорого!