Заметки по CommonJS

• Введение
• Ручное преобразование
• Инструмент преобразования
• Установка экспортируемого значения
• Альтернативный синтаксис
• Загрузка модулей из пакетов CommonJS
• Инструмент оптимизации

Введение

CommonJS определяет формат модулей. К сожалению, он был определён без учёта равных возможностей браузеров по сравнению с другими средами JavaScript. Из-за этого существуют предложения спецификации CommonJS по форматам передачи и асинхронному require.

RequireJS старается следовать духу CommonJS, используя строковые имена для обозначения зависимостей и избегая определения модулями глобальных объектов, но всё же позволяя разработать формат модулей, который хорошо работает в браузере. RequireJS реализует предложение Asynchronous Module Definition (ранее Transport/C).

Если у вас есть модули в традиционном формате CommonJS, вы можете легко преобразовать их для работы с RequireJS. Не все модули преобразуются корректно. Типы модулей, которые могут не преобразовываться корректно:

• Модули, использующие условный код для вызова require, например, if(someCondition) require('a1') else require('a2');
• Некоторые типы циклических зависимостей.

Ручное преобразование

Если вам нужно преобразовать лишь несколько модулей, всё, что вам нужно сделать, это обернуть модуль в этот код:

define(function(require, exports, module) {
    //Put traditional CommonJS module content here
});

ВАЖНО: Аргументы функции всегда должны быть перечислены как require, exports, module, с этими точными именами и в этом точном порядке, иначе возникнут проблемы. Вы можете опустить exports и module из списка, но если они необходимы, они должны быть указаны в точном порядке, показанном здесь.

Инструмент преобразования

Если вам нужно преобразовать много модулей, проект r.js имеет встроенный инструмент преобразования в файле r.js. Укажите путь к каталогу, который вы хотите преобразовать, и каталог вывода:

node r.js -convert path/to/commonjs/modules/ path/to/output

Небольшое количество модулей CommonJS не работают хорошо как модули define(). См. r.js README для получения дополнительной информации.

Установка экспортируемого значения

Некоторые системы CommonJS, в основном Node, позволяют задавать экспортируемое значение путём присвоения экспортируемого значения как module.exports. RequireJS поддерживает этот подход, но есть и другой, более простой способ — просто вернуть значение из функции, переданной в define:

define(function (require) {
    var foo = require('foo');

    //Define this module as exporting a function
    return function () {
        foo.doSomething();
    };
});

С этим подходом вам обычно не нужны аргументы функций exports и module, поэтому вы можете опустить их из определения модуля.

Альтернативный синтаксис

Вместо использования require() для получения зависимостей внутри функции, передаваемой define(), вы также можете указать их через аргумент массива зависимостей define(). Порядок имён в массиве зависимостей соответствует порядку аргументов, передаваемых в функцию определения, переданную define(). Так, в приведённом выше примере, использующем модуль foo:

define(['foo'], function (foo) {
    return function () {
        foo.doSomething();
    };
});

Для получения дополнительной информации об этом синтаксисе см. документацию API.

Загрузка модулей из пакетов CommonJS

Модули в пакетах CommonJS могут загружаться RequireJS путём настройки конфигурации RequireJS для указания местоположения и атрибутов пакета. Для получения дополнительной информации см. раздел API-раздел пакетов.

Инструмент оптимизации

RequireJS имеет инструмент оптимизации, который может объединить определения модулей в оптимизированные пакеты для доставки в браузер. Он работает как командная утилита, которую вы используете в процессе развертывания кода. Для получения дополнительной информации см. документацию по оптимизации.