Как создать и опубликовать свой первый модуль Node.js

Что такое npm?

npm позволяет разработчикам JavaScript обмениваться и повторно использовать код, а также упрощает обновление кода, которым вы делитесь. Недавно вышла бета-версия npm v3.

Предварительные требования

  • Зарегистрируйтесь в GitHub
  • Установите Node.js (npm поставляется с Node, но часто это старая версия)
  • Обновите до последней версии npm (цикл выпуска Node намного медленнее, чем у npm, который еженедельно)
npm install npm@latest -g
If you get an EACCES error, don’t worry! Here's a solution.
  • Создайте учетную запись npm (и подтвердите адрес электронной почты учетной записи npm)
  • Создайте учетную запись Travis CI (используя GitHub)
  • Создайте учетную запись Комбинезоны (с помощью GitHub)

Создайте репозиторий GitHub

  1. Создайте новое репо на GitHub и назовите его «number-formatter» (убедитесь, что вы отметили поле README, добавьте файл. gitignore для Node и лицензию MIT)
  2. Клонировать его локально

Примечание. Завершенный демонстрационный код находится внизу на тот случай, если вы хотите получить высокоуровневое представление макета проекта.

Зачем добавлять лицензию?

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

Да, действительно существует законная Делай, что хочешь, по публичной лицензии.

Скажите npm, кто вы

npm set init.author.name “Channing Tatum”
npm set init.author.email “[email protected]”
npm set init.author.url “http://www.magicmikemovie.com"

Теперь ваши учетные данные будут сохранены в файле ~ / .npmrc и будут использоваться по умолчанию при инициализации пакета npm, поэтому вам не нужно вводить их каждый раз.

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

npm login

Инициализировать пакет npm

Создавая новый модуль, вы хотите описать свой пакет с помощью файла package.json.

npm init

Если вы хотите пространство имен для ваших модулей, сделайте это вместо

npm init --scope=username

Ответьте на все вопросы, которые вам будут предложены.

Что касается версии, давайте начнем с

0.1.0

Когда вы будете вносить изменения в свою библиотеку в будущем, не забудьте обновить версию в соответствии с семантическим управлением версиями (SemVer).

Мне нравится думать о номере версии, который следует за SemVer, вот так

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

Ответьте на вопрос тестовой команды этим

mocha --reporter spec

Теперь вы должны увидеть файл package.json в папке вашего проекта.

Укажите минимальную версию узла

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

"engines": {
  "node": ">=4.2.4"
},

Создать модуль узла

Модуль Node / npm - это обычный файл JavaScript, но он должен соответствовать спецификации модуля CommonJS. UMD, совместимый с CommonJS, тоже работает.

Теперь давайте создадим очень крошечный модуль и назовем файл index.js.

'use strict';

/**
 * Adds commas to a number
 * @param {number} number
 * @param {string} locale
 * @return {string}
 */
module.exports = function(number, locale) {
    return number.toLocaleString(locale);
};

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

Дополнительное примечание: Синдре Сорхус является автором более 600 модулей для npm. Недавно он написал длинный комментарий на GitHub о том, почему мы должны использовать небольшие модули.

Напишите несколько тестов

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

npm i mocha -D
npm i chai -D

Проверьте свой файл package.json, и вы должны заметить, что оба они теперь добавлены в раздел «devDependencies», поскольку они требуются только во время разработки, а не во время выполнения.

Интересные факты!

  • -D аналогично --save-dev.
  • -S - это то же самое, что --save

Создайте папку test и файл test.js внутри нее.

mkdir test && touch test/test.js

Добавьте следующие тесты в файл test.js. Я новичок в написании модульных тестов, поэтому не стесняйтесь делать их лучше.

'use strict';

var expect = require('chai').expect;
var numFormatter = require('../index');

describe('#numFormatter', function() {
    it('should convert single digits', function() {
        var result = numFormatter(1);
        expect(result).to.equal('1');
    });

    it('should convert double digits', function() {
        var result = numFormatter(12);
        expect(result).to.equal('12');
    });

    it('should convert triple digits', function() {
        var result = numFormatter(123);
        expect(result).to.equal('123');
    });

    it('should convert 4 digits', function() {
        var result = numFormatter(1234);
        expect(result).to.equal('1,234');
    });

    it('should convert 5 digits', function() {
        var result = numFormatter(12345);
        expect(result).to.equal('12,345');
    });

    it('should convert 6 digits', function() {
        var result = numFormatter(123456);
        expect(result).to.equal('123,456');
    });

    it('should convert 7 digits', function() {
        var result = numFormatter(1234567);
        expect(result).to.equal('1,234,567');
    });

    it('should convert 8 digits', function() {
        var result = numFormatter(12345678);
        expect(result).to.equal('12,345,678');
    });
});

Запустите наши тесты

Поскольку в нашем файле package.json уже есть следующее через npm init

"scripts": {
  "test": "mocha --reporter spec"
}

Теперь вы можете запускать тесты из командной строки с помощью

npm test

Измените тип репортера с «spec» на «nyan», чтобы немного повеселиться.

Напишите хороший README

Обновите файл README.md (уценка), указав подробности и примеры использования для ваших пользователей, особенно потому, что они будут хорошо видны на GitHub и npm.

Прочтите это, чтобы научиться писать хороший README, а вот хороший шаблон.

Number Formatter
=========

A small library that adds commas to numbers

## Installation

  `npm install @jdaudier/number-formatter`

## Usage

    var numFormatter = require('@jdaudier/number-formatter');

    var formattedNum = numFormatter(35666);
  
  
  Output should be `35,666`


## Tests

  `npm test`

## Contributing

In lieu of a formal style guide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code.

Напоминание: не забудьте обновить README выше, указав свое собственное название проекта, а если вы публикуете модуль с заданной областью действия, обновите его до

@username/project-name

Примечание. Также распространенной практикой является создание отдельного файла CONTRIBUTING.md для ваших рекомендаций по вкладу.

Зафиксировать и отправить на GitHub

Давайте также создадим тег версии.

git add .
git commit -m “Initial release”
git tag v0.1.0
git push origin master --tags

Опубликовать в npm

npm publish

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

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

Однако общедоступные модули с областью действия бесплатны и не требуют платной подписки. Чтобы опубликовать модуль с общедоступной областью действия, установите параметр доступа при его публикации. Этот параметр останется установленным для всех последующих публикаций.

npm publish --access=public

Совет! При создании модуля с заданной областью рекомендуется проверить свой package.json перед публикацией, чтобы убедиться, что имя ваш пакет - «@ username / project-name» - в противном случае он не будет ограничен, и если он должен быть частным, он случайно станет общедоступным.

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

Добавить непрерывную интеграцию

Travis CI - это легкий инструмент непрерывной интеграции, который запускает тесты при каждой фиксации в вашем репозитории GitHub, даже при запросах на вытягивание. Это бесплатно для проектов с открытым исходным кодом.

Войдите в свою учетную запись Travis CI и выполните следующие действия.

Вот как должен выглядеть ваш файл .travis.yml в корне проекта.

language: node_js

node_js:
  - stable

install:
  - npm install

script:
  - npm test

Зафиксировать и отправить на GitHub.

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

Добавить статистику покрытия кода

Istanbul - это библиотека покрытия кода JavaScript, которая проверяет статистику покрытия операторов, ветвей и функций, вставляя строки кода в ваш JavaScript по мере выполнения ваших тестов, а затем сообщая, сколько из вставленных строк было вызвано.

Комбинезон - это средство составления отчетов о тестировании, которое можно интегрировать с Трэвисом. Он красиво форматирует данные о покрытии. Вы можете получить почти все из отчетов из Стамбула, но только локально и менее красиво.

npm i coveralls -D
npm i istanbul -D

Войдите в Coshops с помощью своей учетной записи GitHub, нажмите кнопку ДОБАВИТЬ REPO и переключите переключатель, чтобы включить репо, для которого вы хотите получить статистику покрытия кода. Чтобы использовать комбинезоны, ваш код должен быть размещен на GitHub или Bitbucket.

Настройте файл package.json для Стамбула и Комбинезона, добавив новый скрипт с именем «cover»:

"scripts": {
  "test": "node_modules/.bin/mocha --reporter spec",
  "cover": "node_modules/istanbul/lib/cli.js cover node_modules/mocha/bin/_mocha -- -R spec test/*"
},

И обновите свой файл .travis.yml до этого

language: node_js
node_js:
  - stable
install:
  - npm install

script:
  - npm run cover

# Send coverage data to Coveralls
after_script: "cat coverage/lcov.info | node_modules/coveralls/bin/coveralls.js"

Теперь вы можете запускать тесты и статистику покрытия кода из командной строки с помощью

npm run cover

Теперь зафиксируйте и отправьте на GitHub.

Теперь Трэвис вызовет Стамбул, а Стамбул запустит отчет о покрытии кода только для lcovonly, сохранит эту информацию в extension / lcov.info и направит эти данные в библиотеку Coshops.

Войдите в Комбинезоны, чтобы проверить, все ли выполняется гладко.

Добавьте сладкие значки

Теперь, когда вы настроили репозиторий для запуска тестов на Travis и отправки данных о покрытии в Coshops, вы, вероятно, задаетесь вопросом, как получить эти милые значки в репозиториях GitHub и npm.

Трэвис

Нажмите на переключатель настройки рядом с вашим репозиторием в Travis CI и нажмите на значок значка.

Выберите Markdown и добавьте код в README.

Комбинезоны

Войдите в систему, щелкните свое репо, щелкните раскрывающееся меню «URL-адреса значков» и добавьте код Markdown в свой README.

Зафиксировать и отправить на GitHub.

Трэвис запустит ваши тесты, и вы сможете увидеть статус вашей сборки в README на GitHub.

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

Если сборка не удалась, вы увидите это.

Вы также должны увидеть еще один значок из раздела «Комбинезоны», показывающий статистику покрытия вашего кода.

Выпустить новую версию

Теперь, когда у нас есть замечательные значки на GitHub, давайте разместим их и на npm.

Единственный способ обновить npm - выпустить новую версию, даже если вы просто исправляете опечатку. npm не позволит вам повторно публиковать на тот же номер.

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

npm version <update_type> -m "<message>"

где update_type - один из типов выпуска семантического управления версиями:
patch, minor или major .

Итак, давай сделаем

npm version patch -m "Version %s - add sweet badges"

% s = номер новой версии.

Эта команда изменит номер версии в package.json, добавит новую фиксацию и пометит ее этим номером выпуска.

Примечание. Перед запуском версии npm ваш рабочий каталог Git должен быть чист.

После натыкания номера версии

git push && git push --tags (or git push origin master --tags)
npm publish

Теперь, если вы перейдете к опубликованному модулю в npm, вы должны увидеть свой новый выпуск с двумя милыми значками!

Протестируйте свой модуль

Создайте новый каталог и файл package.json.

{
  "dependencies": {
    "project-name": "*"
  }
}

Затем из командной строки

npm i

Создайте файл index.js со следующим содержанием

var numFormmater = require('project-name');

var formattedNum = numFormmater(234324234);

console.log(formattedNum);

Напоминание. Если вы опубликовали модуль с заданной областью действия, измените название проекта на

@username/project-name

Затем из командной строки

node index

Вы должны увидеть журнал консоли

234,324,234

Больше информации

Особая благодарность

✉️ Подпишитесь на рассылку еженедельно Email Blast 🐦 Подпишитесь на Codeburst на Twitter и 🕸️ Изучите полную веб-разработку .