Meteor Package API Example

Context

In the past few days i was playing around with meteor framework, and was trying to install aloha editor. I realized that there was already an atmosphere package called aloha-meteor which allowed me to install it with meteorite: mrt add aloha-meteor.

The problem was that for some reason no translation files were included in this package, and i wanted to use it in pt-BR. So i forked the package and started doing some modifications, but got stuck pretty soon because i needed to use meteor's package api ( which is currently private ), and couldn't find its documentation anywhere. So i decided to document meteor's package api methods for future reference.

Package API

Most of this documentation was gathered looking at meteor's packages.js and other packages.

First of all, you need a file called 'package.js' inside of your package. Possible methods you can use there are: (by example)

Package.describe({
  summary: "Package Description. Will appear with meteor list",
  internal: false, // optional, will not show with meteor list if false
  environments: ['client', 'server'] // optional. Supposedly specifies environments to load package, but i did not find any package that specifies this key.
});

Package.on_use(function (api, where){      
  // calls another package's on_use method
  api.use('package name', 'client')
  api.use('package name', ['client', 'server'])
  api.use('package name', where || 'client')

  // add file(s) with specified environment(s)
  api.add_files('file_name.js', 'client');
  api.add_files('file_name.js', ['client', 'server']);
  api.add_files(['file_name.css', 'file_name.html'], 'client');
});

Package.on_test(function (api, where){
  // same api methods as Package.on_use's callback function parameter
});

// used to describe a new extension file type
Package.register_extension("coffee", function (bundle, source_path, serve_path, where) {
  // look at https://github.com/meteor/meteor/blob/master/packages/coffeescript/package.js for example
});

One of the problems that i run into when trying to create my aloha-editor package, is that by default it loads some of its javascript files asynchronously, and so it expects those js files to exist as static files. However, api.add_files does not add js files as static ones, rather it executes the file's contents. api.add_files only adds files as static ones ( which would equal as putting them in your app's public folder ) if there is no defined handler for the file's extension type.