2013 Meteor NPM Packages

Update this solution describes how to effectively use the new Npm system in Meteor.

What is the current method of using NPM packages in Meteor?

_{As of March 22, 2013, there is no official documentation on this.}

There are several questions about this, notably this one, however the solution seems outdated: the engine branch no longer exists, and I haven't been able to find anything on Npm.require in Meteor.

Another solution, posted here, instructs to install into the .meteor/ build folders. As I am installing to Heroku, this doesn't seem like a valid solution, as the buildpack uses meteor bundle to bundle the program before running it. Thus, the temporary build folders don't seem like a valid option.

What has happened to Npm in meteor? What's the latest way of using Npm packages?

On a related note, I'm trying to use the Amazon SDK (for s3) - would it be better to just package it as a Meteorite package instead?

Arunoda has created an NPM Atmosphere package that allows you to use any NPM module like you're used to. It's very simple.

First, mrt add npm.

You can also install the package by using meteor-npm command from npm install -g meteor-npm.

Next, make a packages.json file in your root project directory, with the package names and versions:

{
    "foobar": "0.3.5",
    "loremipsum": "2.1.4"
}

Finally, use them with Meteor.require, like this: var FooBar = Meteor.require('foobar');

The current way of using NPMs in Meteor

1. Replace the x's below with the NPM name
2. Place the files outline below in /meteor-project-root/packages/x/
3. meteor add x
4. To use it just call X in your code (X.function())

x.js --------

X = Npm.require('x');

package.js --------

Package.describe({
  summary: "Meteor smart package for x node.js package"
});

Npm.depends({
  "x": "0.1.1"
});

Package.on_use(function (api) {
  api.add_files("x.js", ["client", "server"]);
});

Note: some packages will only work on client or server, if you are having issues, try only include the side you are going to use it on.

I have been using the fantastic "browserify", which works like a charm. This is an alternative to using Arunda's NPM Atmosphere package, or using Npm.require with package.js, that arguably has some advantages:

1. My code can use plain old "require" instead of Npm.require or Meteor.require. Obviously this is not a huge deal, but if I want to use this code outside Meteor it's nice to feel it's not dependent on Meteor.
2. I don't have to worry about whether Meteor will once again change the way it thinks about Npm integration again.
3. It allows me to use local development version of my own npm modules using npm link.

Here's how it works:

1. I create a separate project for npm dependencies in a hidden .npm folder
2. I use browserify to create a bundle.js that will be loaded by meteor
3. I use grunt watch to make sure that every time I install a new npm package, the bundle.js is updated

Here's my directory structure:

my_meteor_project/
    lib/
        bundle.js

    .npm/
        node_modules
        README.md
        Gruntfile.js
        entrypoint.js
        package.json

Here's an example of entrypoint.js (unfortunately I have to use globals so that assert, url, and _ are available in Meteor code)

assert = require('assert');
url = require("url");
_ = require('underscore');

Here's the gruntfile:

module.exports = function(grunt) {
  grunt.initConfig({
    watch: {
      build: {
          files: ['./entrypoint.js', './package.json'],
          tasks: ['browserify2'],
          options: {
          }
      }
    },
    browserify2: {
      compile: {
        entry: './entrypoint.js',
        compile: '../lib/bundle.js'
      }
    },
  });

  grunt.loadNpmTasks('grunt-browserify2');
  grunt.loadNpmTasks('grunt-contrib-watch');
  grunt.registerTask('build', ['browserify2']);
};

I then use grunt watch to watch for changes to entry.js or new NPM installs

$ cd .npm
$ grunt watch:build &
[2] 44617
$ Running "watch:build" (watch) task
Waiting...

And then if I install an npm module, or modify entrypoint.js, bundle.js is updated:

$ npm install url -save
npm http GET https://registry.npmjs.org/punycode
npm http GET https://registry.npmjs.org/querystring
npm http 304 https://registry.npmjs.org/punycode
npm http 304 https://registry.npmjs.org/querystring
[email protected] node_modules/url
├── [email protected]
└── [email protected]
$ OK
>> File "package.json" changed.

Running "browserify2:compile" (browserify2) task
File written to: ../lib/bundle.js

Done, without errors.
Completed in 1.256s at Thu Jul 11 2013 11:36:22 GMT-0600 (MDT) - Waiting...

You can use https://atmospherejs.com/meteorhacks/npm

meteor add meteorhacks:npm

And then you can setup your package.json file:

{
  "redis": "0.8.2",
  "github": "0.1.8"
}

And use these packages:

var GithubApi = Meteor.npmRequire('github');