Node.js global module - Как создать модуль запускающийся глобально отовсюду

Запускать созданные вами модули для Node.js через командную строку с указанием полного пути до модуля достаточно неудобно:

node ../path/to/mytool/script.js --arguments somevalue

Вместо этого хочется делать это также коротко, как делают это TypeScript, Webpack или Cordova:

tsc do-something
cordova do-something
nodemon do-something

Гораздо лучше было бы запускать ваш модуль также:

mytool do-something

В этой статье вы узнаете, как создать модуль, который будет доступен глобально после установки из NPM.

1. Создание обычного модуля.

Сперва создадим обычный модуль. Пусть его название будет "my-toolkit".
Для этого создадим папку с именем "my-toolkit".
Внутри папки "my-toolkit создадим папку "lib".
Внутри папки "lib" создадим файл "index.js" со следующим кодом:

// ./lib/index.js

/**
 * Функция выводит текст в консоль.
 *
 * @param {string_to_say} String строка с текстом для вывода в консоль.
 */
function say (string_to_say) {
    return console.log(string_to_say);
}

exports.say = say;

Код данного файла будет являться главным для нашего модуля. Функция say() будет выводить переданный текст в консоль.

Создадим для нашего модуля в папке "my-toolkit" файл "package.json" для того, чтобы его можно было публиковать и устанавливать через NPM со следующим содержимым:

{
    "name": "my-toolkit",
    "version": "1.0.0",
    "description": "My custom global module",
    "author": "Noname",
    "license": "MIT",
    "main": "./lib/index.js",
    "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1"
    }
}

2. Создание файла для глобализации модуля.

Для того, чтобы сделать простой модуль глобальным создадим внутри папки "my-toolkit" папку "bin".
Далее в папке "bin" создадим файл "demo-global.js" со следующим содержимым:

#!/usr/bin/env node

var myLibrary = require('../lib/index.js');

myLibrary.say('Hello, World!');

Важное замечание.

Обратите внимание на первую строку (#!/usr/bin/env node), которая позволит NPM после инсталляции вашего модуля корректно создать для него файл исполнителя (имя-команды.cmd).

В случае работы на Windows при выполнении кода из файла будет проигнорирована линия #!/usr/bin/env node и код модуля будет выполнен, как обычный JavaScript-файл, с расширением .js.

3. Подготовка модуля для глобальной инсталляции.

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

{
    ...
    "bin": {
      "dosomethingawesome": "./bin/demo-global.js"
    },
    ...
}

Этого будет достаточно для регистрации вашего модуля, если кто-либо проведет его инсталляцию из NPM с указанием флага -g:

npm install -g mymodule

После установки вашего модуля на Windows NPM самостоятельно создаст обертку dosomethingawesome.cmd в папке с установленным модулем для того, чтобы пользователи могли вызывать код вашего модуля по прописанной вами короткой команде dosomethingawesome.

Обратите внимание, что в свойстве "bin" вы можете прописать сколько угодно команд, если вы имеете, например, несколько исполняемых файлов, для которых хотите прописать пути в переменной PATH в процессе инсталляции вашего модуля из NPM.

Если ваш модуль предназначается для использования только глобально, тогда вам следует в файл "package.json" добавить свойство preferGlobal со значением true, которое заставит NPM выводить на экран предупреждение в случае, если ваш модуль попытаются установить локально без флага -g:

{
    ...
    "preferGlobal": true,
    ...
}

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

В итоге после всех изменений код файла "package.json" будет иметь следующий вид:

{
    "name": "my-toolkit",
    "version": "1.0.0",
    "description": "My custom global module",
    "author": "Noname",
    "license": "MIT",
    "main": "./lib/index.js",
    "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1"
    },
    "bin": {
      "dosomethingawesome": "./bin/demo-global.js"
    },
    "preferGlobal": true
}

Теперь ваш модуль готов к глобальной инсталляции.

4. Инсталляция вашего глобального модуля.

На последнем шаге вы решаете как инсталлировать ваш модуль.
Вы можете инсталлировать его из локального источника (папки), опубликовать его в Github, затем в NPM, откуда будет инсталлировать его командой:

npm install -g my-toolkit

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

npm install -g C:\my-toolkit

Не забудьте, что в команде для инсталляции обязательно должен присутствовать флаг -g.

После инсталляции ваш модуль будет доступен для вызова по команде:

dosomethingawesome

5. Деинсталляция вашего глобального модуля.

Для деинсталляции (uninstall) вашего модуля (даже если он был инсталлирован из локальной папки, расположенной на вашем компьютере) выполните команду:

npm uninstall -g my-toolkit

6. Примечания.

Если вы хотите сделать что-то более сложное, то можете поиграть с передачей аргументов в ваш глобальный модуль. Пример следующего кода для файла "demo-global.js", расположенного в папке "bin", позволит принимать переданные в ваш модуль аргументы с помощью короткой команды dosomethingawesome:

#!/usr/bin/env node

// Удалить нулевой и первый аргумент: node и script.js.
var args = process.argv.splice(process.execArgv.length + 2);

// Получить первый аргумент.
var name = args[0];

var myLibrary = require('../lib/index.js');

//  Вывести переданный текст в консоль.
myLibrary.say('Hello, ' + name + '!');

В итоге выполнение команды:

dosomethingawesome Boris

выведет на экран:

Hello, Boris!