Custom Meteor Package Publishing – Complete Guide

Posted on May 05, 2017

Custom Meteor Package Publishing – Complete Guide

Search your custom meteor package on atmosphere js

As we all know that Meteor has a vast community and open-source packages which makes the development of a Meteor application much easier. These packages can be found on atmospherejs.com. It would be great if we could have our own custom meteor package on atmospherejs and contribute to this vast community. So, friends, this blog is solely for that purpose and we will cover everything from creating your custom meteor package, testing, publishing, deletion, to updating your atmosphere package. Let’s begin!

 

Creating a Custom Meteor Package

Step 1

Creating your first Meteor package is pretty simple:

First of all, execute the following command in your terminal:

meteor create --package myname:my-package

Where “myname” is your Meteor Developer Account username. As a result, this command will create a local meteor package with some boilerplate code in addition to this directory structure

my-package
├─ README.md
├─ package.js
├─ my-package-tests.js
└─ my-package.js

Note: If the command “meteor create –package myname:package” is executed inside a meteor app then it will create the package in that app’s “packages/” directory. When executed outside an app, it will just create a standalone package directory as shown above.

Let’s create a new Meteor package called: “nodexperts:demopackage”. We will run:

meteor create --package nodexperts:demopackage
Step 2

Below given is the boilerplate code already written in the package.js file when you executed the package create command

Package.describe({
    name: 'nodexperts:demopackage',
    version: '0.0.1',
    summary: '', // Brief, one-line summary of the package.
    git: '',  // Git URL for the source code for this package.
    // By default, Meteor will default to using README.md for documentation.
    // To avoid submitting documentation, set this field to null.
    documentation: 'README.md'
 });
Package.onUse(function(api) {
   api.versionsFrom('1.4.4.1');
   api.use('ecmascript');
   api.mainModule('demopackage.js'); //entrypoint for the package
});

Package.onTest(function(api) {
   api.use('ecmascript');
   api.use('tinytest');
   api.use('nodexperts:demopackage');
   api.mainModule('demopackage-tests.js');
});

In the above package.js file you can add the git url and a short summary about your package. This helps users to see your source code on the git url and get the idea about what your package is for from the summary.

Step 3

You can add js , css , assets and dependencies required by the package in the following ways

Add Javascript files

To add JavaScript files to your package, specify an entrypoint with api.mainModule() in the package’s onUse block (this block is created by the meteor –create package command in step 2)

Package.onUse(function(api) {
   api.mainModule('demopackage.js');
});

From the “demopackage.js” entrypoint you can load other files just like in any other meteor app.

Selective loading of files

To selectively load files on the client and server you can use

Package.onUse(function(api) {
   api.mainModule('demopackage-client.js', 'client'); //loads only on client
   api.mainModule('demopackage-server.js', 'server'); //loads only on server
});
Add CSS files

To add CSS files to a package you can use api.addFiles()

Package.onUse(function(api) {
   api.addFiles('demopackage.css', 'client');
});
Adding SASS,LESS or Stylus Mixins/variables

To add Sass, Less, or Stylus mixins/variables as well we can use the api.addFiles().

You can also export bits of reusable mixins and variables. Exporting is not limited to just exporting CSS. To get more details see this link:

Package.onUse(function(api) {
   api.addFiles('demopackage.scss', 'client');
});

We can also add multiple files as follows:

 Package.onUse(function(api) {
   api.addFiles([
    'stylesheets/_util.scss',
    'stylesheets/_variables.scss'
   ], 'client', {isImport: true});
});
Adding Assets like fonts, icons etc

To add assets like fonts, icons or images, to your package using api.addAssets()

Package.onUse(function(api) {
   api.addAssets([
      'font/OpenSans-Regular-webfont.eot',
      'font/OpenSans-Regular-webfont.svg',
      'font/OpenSans-Regular-webfont.ttf',
      'font/OpenSans-Regular-webfont.woff',
   ], 'client');
 });
Adding Dependencies

Your custom meteor package can also depend on other meteor packages so to do that we can use api.use() as follows

Package.onUse(function(api) {
    // This package depends on 1.3.3 or above of simple-schema
    api.use('aldeed:[email protected]');
});

Another scenario is where your custom meteor package depends on a NPM module so for that we can use

Npm.depends({
   d3: '4.0.0'
});

You can import the dependency from within your package code in the same way that you would do inside an application:

import d3 from 'd3';

Testing your package

We have created our package, but are we sure it’s working as it should be? For making sure our package works properly too, we should do testing of the package.

Let’s start:

You have to create your mocha tests in files following the same *.test[s].* naming convention in a test folder which is in your package folder.

For example : demopackage / test / *.test[s].*

Now we will add a package to run the tests,

meteor add dispatch:mocha

Now add dispatch:mocha to run test and test files in your package.js to only run test files while running test.

Package.onTest ( function ( api ) {
    var packages = [ ' ecmascript ' , ' dispatch:mocha ' ];
    api.use( packages, ' server ' );
    api.addFiles( [ ' test / *.tests.* ', 
‘ test / *.tests.* ’ ] , server); // Add any files with mocha tests.
 })

Finally, we will be seeing our package testing by the following command :

TEST_WATCH=1 meteor test-packages ./ --driver-package dispatch:mocha

OR

You could also add the above command in package.json file in scripts property and run via npm command.

Publishing your package

Finally, your package is ready, now you can use this command from within the package’s directory to publish it and make it available on Atmosphere.

meteor publish --create

Your package will then be published on atmospherejs.com and you can find it using their search option.

Update your package

To update the codebase of the package run the following command from your package directory

meteor publish

Else, you can use the following command if you just want to update the summary, description of the package

meteor publish --update

You can see the results using ‘meteor show’ command.

Removing your package

There is no way to actually remove/unpublish your package from AtmosphereJS but you can stop your package from appearing in AtmosphereJS search by executing the following command in terminal from your package directory

meteor admin set-unmigrated

Note: – This will only hide the package when you run “meteor search” command, the users who know the name of your package can still add it and use in their Meteor application via ”meteor add <package-name>”.

Install , Import and use your package

To install your published package to a Meteor application use the following command

meteor add nodexperts:demopackage

Now since your package has been installed, therefore you can access all the variables or classes that you have exported in your package code as shown below.

import DemoClass from 'meteor/nodexperts:demopackage';