Meteor Packages in CoffeeScript since 0.6.5

Version 0.6.5 of Meteor introduced major changes regarding its package system. I’m still working on a package to provide full text search and I’m using CoffeeScript as the language of choice. After updating to the new version of Meteor, I learned a few things that are worth sharing with you, in case you are in a similar situation.

Meteor now provides source maps for CoffeeScript, which basically means, that you get more accurate error messages with references to the CoffeeScript sources, i.e. the (almost correct) row and column number. Prior to this addition you had to guess from the compiled JavaScript, to pinpoint the problem.

Packages now have their own namespace. This reduces the chance of unintended shadowing of symbols (variable names) from the global namespace. To make package functionality accessible in an app, you need to export those symbols explicitly. You do this in the package definition file: package.js. In the Package.onUse function you do this by calling:

api.export(‘symbol’);

You might want to provide a second parameter to control the visibility on the server and the client

api.export(‘clientSymbol’,’client’);
api.export(‘serverSymbol’,’server’);
api.export(‘bothSymbol’,[‘client’,’server’]);

Client and server is the default, though, and might be omitted. A third parameter might be passed to limit the visibility to the test execution:

api.export(‘symbol’,[‘client’,’server’],{testOnly: true});

In your packages sources (in CoffeeScript) you have to consider the following rules:

  • Plain root level symbols are file-scoped, i.e. not visible in other files of the package
  • Symbols starting with @ are package globals, i.e. visible in all files of the package.
  • Exported symbols are visible in all files of the package and in the application code. But must not start with a @-character.

So in case you want to have a package-global symbol and want to export it anyway you must omit the @. In case you want to have an always visible package-global variable and want to export it, only when testing, you need to do something like this:

@Length = (string) -> string.length
Length = @Length

And export Length like shown above in package.js.

And of course, don’t forget to add CoffeeScript to the build chain. Again in package.js, add:

api.use(‘coffeescript’,[‘client’,’server’]);

to enable Meteor to read and interpret your package sources written in CoffeeScript.

Meteor’s internal package system is still very much in flux and more changes are to be expected. So stay tuned for further revelations.

Advertisements

4 thoughts on “Meteor Packages in CoffeeScript since 0.6.5

  1. Jim Mack says:

    Oh, oh, thank you so much. My arc of learning Meteor coincided with this change in packages, just when I was sure I was getting everything, and I never found this info. A huge confidence blow!

  2. Dan D says:

    Was wondering why Meteor wouldn’t run server-side .coffee files in packages… api.use(‘coffeescript’,[‘server’]); was missing!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s