Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ovcharik/meteor-packages-tutorial

Meteor package examples
https://github.com/ovcharik/meteor-packages-tutorial

Last synced: 7 days ago
JSON representation

Meteor package examples

Awesome Lists containing this project

README 

        
# Руководство по созданию пакетов для [Meteor](https://www.meteor.com/)



В данном руководстве будет рассмотрено несколько примеров пакетов для Meteor и некоторые особенности этих пакетов.



## Перед началом



Если вы планируете публиковать свои пакеты для общественного доступа, необходимо завести аккаунт разработчик. Сделать это можно на сайте [Meteor](https://www.meteor.com/). В верхнем левом углу есть форма для регистрации. После регистрации необходимо войти в систему на вашем компьютере, выполнив команду



    $ meteor login



Имя пакетов имеет следующую структуру: `username:packagename` - где `username` - имя пользователя и если вы являетесь контрибьютором этого пакета, то `username` должен совпадать с именем пользователя, указанного при регистрации. В противном случае вам не удастся опубликовать пакет*.



Для быстрого создания каркаса вашего пакета можно воспользоваться командой



    $ meteor create --package 



Выполним эту команду и посмотрим что в итоге получилось:



    $ meteor create --package hello

    hello: created



В текущей папке был создан проект с именем `hello` (у меня имя не правильное и его не получится опубликовать, но я и не собираюсь). В самом проекте сейчас содержится три файла: `hello.js`, `hello-tests.js`, `package.js`. Пока что перые два файла особого интереса не представляют, давайте лучше ознакомимся с `package.js`.



## package.js



Данный файл состоит из трех основных секций: описание пакета, секция сборки и секция тестирования. Опционально в этом же файле можно управлять npm зависимостями. Содержание файла выглядит следующим образом



```javascript

/*

  Общая информация о пакете

*/

Package.describe({

  // версия пакета согласно http://semver.org/

  version: "1.0.0",

  // короткое описание проекта

  summary: "What this does",

  // имя пакета, по умолчанию именем является

  // названием директории содержащей пакет

  name: "hello",

  // ссылка до исходников проекта на github

  git: "https://github.com/something/something.git"

});



/*

  Данная секция определяет ваш пакет, здесь указываются параметры сборки,

  зависимости, экспорт и прочее

*/

Package.onUse(function(api) {

  // версии пакетов ядра берутся из указанной версии

  api.versionsFrom('[email protected]');

  // зависимости

  api.use('underscore');

  api.use('mrt:[email protected]', 'client');

  // доступ пользователю к зависимым пакетам

  api.imply('mrt:jquery-ui');

  // Подключение файлов проекта

  api.addFiles('hello.js', 'server');

  // Экспорт объектов пакета

  api.export('Hello', 'server');

});



/* Информация для тестирования пакета */

Package.onTest(function(api) {

  // подключение библиотеки tinytest

  api.use('tinytest');

  // подключение текущего пакета

  api.use('hello');

  // добавление файлов тестов

  api.addFiles('hello-tests.js');

});



/* Здесь можно указать npm зависимости */

Npm.depends({

  "async": "0.9.0"

});

```



#### Package.describe



С помощью функции `Package.describe(options)` вы можете предоставить основную информацию о пакете. В объект `options` обязательным параметром является только `version`, и дополнительно можно указать имя пакета, короткое описание и ссылку на репозиторий в github.



* `version` - версия пакета согласно спецификации [Semantic Versioning](http://semver.org/), обязательный параметр, при публикации новой версии этот параметр должен инкриминироваться

* `summary` - короткое описание пакета, буквально в двух словах, оно будет отображаться при поиске пакета

* `name` - имя пакета, по умолчанию используется название директории в котором содержится пакет, имя пакета должно иметь следующий формат `username:packagename`

* `git` - ссылка на github репозиторий



#### Package.onUse



В метод `Package.onUse` должна передаваться функция, которая будет определять зависимости проекта, файлы проекта, экспорт и доступ пользователя к зависимостям.



* `api.use(, [architecture], {options})` - добавление в проект зависимости `packagename`

  * `[@version]` - вы можете указать версию зависимости, например если вы укажите `[email protected]` для использования, то будет использоваться пакет версии `1.0.0` или выше, но совместимый с этим релизом

  * `[architecture]` - если вы хотите что бы зависимый пакет использовался только на сервере или клиенте, то в качестве этого параметра укажите `server` или `client` соответственно, если не казать данный параметр, то зависимость будет доступна в обоих средах

  * `options`

    * `weak` - флаг устанавливающий слабую зависимость. Если этот флаг установлен, то указанный пакет не будет загружен в проект, при условии, что больше он нигде не указан (в зависимостях других пакетов или в самом проекте)

    * `unordered` - если флаг установлен, то ваш пакет может быть загружен в проект раньше, чем указанная зависимость

* `api.versionsFrom()` - использование версий пакетов ядра из указанного релиза. По умолчанию версии берутся из текущей версии Meteor на проекте.

* `api.imply( | [, )` - передав в эту функцию имя пакета или массив с именами, вы можете предоставить доступ пользователя к зависимым пакетам

* `api.export(exportedObject, [architecture])` - объекта, первым параметром передается имя экспортируемого объекта. Например если у вас в пакете есть глобальный объект `MyCoolObject` с определенной функциональность, и вы хотите предоставить доступ к нему из пользовательского приложения, то просто используйте этот метод, все остальные объекты экспортироваться не будут. Также вы можете ограничить область видимости этого пакета передав параметр `architecture`, который может принимать значения `client`, `server`

* `api.addFiles( | [, ], [architecture])` - добавление файла или массива файлов к пакету, файлы загружаются в проект в порядке соответствующем вызовам данного метода.



#### Package.onTest



Секция определяющая тесты для пакета. Метод похож на `Package.onUse`, только вы можете подключить свой пакет к тестам воспользовавшись методом `api.use` и передав туда параметром имя вашего пакета, все зависимости при этом будут подключены автоматически. Для тестирования обычно используют библиотеку `tinytest`, но вы можете воспользоваться любым функционалом.



#### Npm.depends



Чтобы подключить к проекту npm зависимости, можно передать в этот метод объект, где ключом является имя пакета, а значением его версия. Для подключения библиотеки в проект, нужно воспользоваться функцией `Npm.require`, куда передается имя пакета, а возвращается библиотека, работает как `require` в `nodejs`.



## Тестирование пакета



Есть два основных пути для тестирования пакета



#### Интеграционные тесты



Вы можете создать Meteor приложение и в папку `pakages` перенести свой пакет (достаточно, кстати, просто создать символьную ссылку на пакет), а после воспользоваться командо



    $ meteor add 



где `` имя директории с пакетом. После этого ваш пакет будет доступен в проекте и вы можете отладить его и написать интеграционные тесты.



#### Модульное тестирование



Это выполнение тестов описанных в файле `package.js` в секции `onTest`. Для запуска тестов нужно воспользоваться командой



    $ meteor test-packages 



Вместо имени пакета можно передать путь до него, например для запуска тестов из папки с пакетом достаточно запустить `meteor test-packages ./`.



## Примеры



В папках к данному проекту собранно несколько пакетов, в ближайшее вермя постараюсь добавить к ним описание.



## Ссылки



1. [Описание системы пакетов на английском, пока находится в разработке](https://meteor.hackpad.com/Unipackage-tvas8pXYMOW)