Опубликовать npm-пакет легко. Поддерживать его — другое дело
Чтобы выпустить пакет в npm, нужны три вещи: код, package.json и одна команда. Это делается за день.
Я выпустил три пакета. И главное, что я о них понял, — дело не в процессе публикации, а в том, что происходит после.
Потому что, как только пакет вышел, он перестаёт быть только вашим. Им пользуются люди, их код зависит от вашего, и вы больше не свободны.
Эта статья об этом.
До публикации: три обязательные вещи
Техническая часть проста, но три вещи нужно сделать правильно с самого начала, потому что менять их потом дорого.
1. Явно определите, что экспортируется.
{
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.cjs"
}
},
"files": ["dist"]
}Поле files важно: без него в пакет попадут тестовые файлы, конфигурации и случайный мусор. Перед публикацией посмотрите npm pack --dry-run, что именно уходит, — это привычка на одну секунду, а спасает от многих неловкостей.
2. Сведите зависимости к минимуму.
Каждая зависимость становится обязательной для того, кто использует ваш пакет. Написать десять строк кода вместо подключения библиотеки ради маленького хелпера почти всегда правильнее.
Если пакет работает с каким-то фреймворком, укажите его в peerDependencies, а не в dependencies. Иначе у пользователя окажутся две копии фреймворка и появятся непонятные ошибки.
3. README должен начинаться с работающего примера на первом экране.
Люди не читают документацию, они копируют. Пусть в первых двадцати строках README будет рабочий, полный, готовый к копированию пример. Всё остальное — ниже.
Версионирование: неверное понимание ломающего изменения
Семантическое версионирование знают все: старшее число — ломающее изменение, среднее — новая возможность, младшее — исправление.
Проблема в определении. Многие под «ломающим изменением» понимают только изменение API. На деле список гораздо длиннее:
- Изменилось имя функции или порядок параметров — это очевидно
- Изменилось значение по умолчанию — API тот же, поведение другое
- Изменился тип ошибки — кто-то мог проверять его внутри
catch - Поднялась минимальная версия Node или фреймворка — у людей на старом окружении пакет перестанет работать
- Изменился формат вывода — например, в возвращаемый объект добавилось поле, а кто-то сравнивал его целиком
Последний пункт спорный, но практическое правило такое: если изменение способно сломать чей-то работающий код, оно ломающее.
Я несколько раз видел, как выпущенное мной «мелкое исправление» ломало чей-то код. Теперь при сомнениях я поднимаю старшее число. Номер версии стоит дёшево, доверие — дорого.
Самое времязатратное: issue
Написание кода — небольшая часть поддержки пакета. Основное время уходит на общение с людьми.
Issue делятся примерно на три типа.
Настоящие ошибки. Они самые ценные — кто-то провёл вам бесплатное тестирование. Но приходят они обычно без данных для воспроизведения. Я добавил шаблон issue, и это заметно улучшило ситуацию: версия, окружение, ожидаемый и фактический результат.
Вопросы по использованию. «Как мне сделать вот это?» Обычно это признак пробела в документации. Отвечая, я добавляю ответ ещё и в README — тогда вопрос не приходит второй раз.
Запросы новых возможностей. Самый сложный тип, потому что здесь придётся говорить «нет».
Научиться говорить «нет»
Для меня это оказалось самой трудной частью.
Человек пользуется вашим пакетом и что-то просит. Отказывать неловко. Но каждая добавленная возможность — это вечное обязательство: её нужно поддерживать, тестировать, документировать и избегать несовместимых с ней изменений.
Мой критерий такой: относится ли запрос к основной задаче пакета?
Если да — обсуждаем. Если нет — честно говорю: это за пределами области пакета, но вы можете сделать это сами вот так.
Такой ответ полезен и людям. Расплывчатое «посмотрю» заставляет их ждать. Чёткое «нет» позволяет искать другое решение.
Хорошо работает описание области в README: что пакет делает и чего он не делает. Второй список не менее полезен, чем первый.
Честно о выгорании
Поддержка открытого пакета — добровольное дело, но начинает ощущаться как обязанность.
Issue открыт, вы не ответили, и это висит над вами. Через несколько месяцев вы начинаете избегать заходить в репозиторий.
Мне помогли три вещи.
Запишите ожидания. Достаточно одной фразы в README: пакет поддерживается в свободное время, ответы могут задерживаться. Это честно и снимает давление.
Объявите пакет завершённым. Не всякий код обязан постоянно расти. Если пакет выполняет свою задачу, он может быть «стабильным и законченным». Это не заброшенность, а состояние.
Если бросаете — скажите об этом. Худший вариант — молча исчезнуть. Если вы больше не будете поддерживать пакет, напишите это в README. Люди смогут спланировать, а кто-то, возможно, возьмёт его на себя.
Стоит ли оно того
Да, но причина не та, которую ожидают.
Открытый код не приносит известности, а предложения о работе приходят редко. Настоящая отдача в другом.
Первое — меняется качество кода. Когда вы пишете код, который будут читать и использовать другие, вы совершенно иначе относитесь к именам, документации и граничным случаям. Эта привычка потом переходит и на рабочий код.
Второе — вы видите собственные допущения. Оказывается, очевидное для вас совсем не очевидно другому человеку. Такому знанию о проектировании API не научит ни одна книга.
Если вы думаете выпустить пакет, мой совет прост: сделайте область маленькой. Пакет, который хорошо делает одну вещь, можно вести годами. Пакет, который делает всё, вымотает вас за полгода.