Сборник best practices от Liran Tal по Node.js CLI. 37 рекомендаций в 10 группах — от техники и безопасности до удобства работы в терминале. В каждом бест практисе есть описание, почему это важно и как не напортачить, ссылки на источники или готовые решения (например, в виде npm-пакетов). Также есть скилл, чтобы встроить все эти бест практисы в агента. MUST READ, если хотите делать крутые cli. Сборник очень хороший.
1. Command Line Experience — UX в терминале:
- Поддерживайте POSIX-аргументы (
-abc = -a -b -c, короткие и длинные флаги)- Проектируйте CLI так, чтобы им было легко и удобно пользоваться
- Запоминайте данные и настройки между запусками
- Поддерживайте цвета и их отключение
- Поддерживайте rich interactions — select, autocomplete, spinner/progress bar
- Делайте кликабельные hyperlinks в терминале (URL и
file:line:col)- Zero configuration — запуск без конфига и умный детект
- Обрабатывайте SIGINT
2. Distribution — как упаковать:
- Минимум зависимостей
- Фиксируйте версии в
npm-shrinkwrap.json- Cleanup конфигов при uninstall
3. Interoperability — CLI как часть unix toolchain:
- Умейте обрабатывать STDIN в пайпах (
curl … | your_cli)- Умейте выводить structured output (
--json) для парсинга и пайпов- Несколько советов для поддержки кросс-платформенности
- Уважайте приоритет конфигурации: CLI args → env → project → user → system
4. Accessibility
- Docker-образ для тех, у кого нет Node.js
- Graceful degradation /
--json для CI и слабых терминалов- Поддержка актуальных Node.js версий, понятная ошибка на старых
-
#!/usr/bin/env node в shebang5. Testing — не доверяйте locale в assert'ах на текст help/output
6. Errors — ошибки, которые помогают:
- Используйте коды ошибок (например,
E4002)- Сообщения об ошибках должны вести к действию — не «что-то сломалось», а «сделай X»
- Предоставьте дебаг режим
- Используйте правильные exit codes
- Упростите репортинг багов
7. Development — package.json hygiene:
- Советы по использованию поля
bin- Используйте относительные пути
- Не тащите в
files лишнее8. Analytics — должна быть опциональной
9. Versioning
- Всегда предоставляйте флаг
--version- Используйте semver
- Показывайте версию в help/errors и package.json
- Старайтесь быть обратно совместимыми
- Публикуйте релизы в npm
- Пишите понятные release notes
10. Security — минимизируйте возможность argument injection
Также в приложении есть сравнительная таблица CLI-фреймворков и ссылки на обучающие материалы.
https://github.com/lirantal/nodejs-cli-apps-best-practices
#development #nodejs #cli #best-practices
