Official Meteor integration directly from 3rd party libraries

[dandv]

If you're looking for a popular 3rd party library on Atmosphere, chances are you'll find several wrappers, in various states of maintenance. To avoid this problem, several Meteor community members have started to provide authoritative, high-quality, Meteor integrations of 3rd party libraries, complete with tests and grunt scripts. These are forks of the library rather than Git submodules, because forks allow modifying the source to support Meteor (if necessary) and one can still pull upstream changes without having to re-apply the integration changes.

These forks live in the MeteorPackaging GitHub organization. This org was created so that multiple developers can collaborate on maintaining an integration in a centralized location. Now that Meteor's Package API is stable, we can submit PRs to popular JS library maintainers to add official Meteor integration. Some maintainers will accept the PR - great, we have integration straight from the source, with same-day updates on Atmosphere. Some won't accept the PR, in which case we continue with the MeteorPackaging fork.

I started this effort in November 2014, spoke about it at DevShop SF, and here's where we are now.

Going forward

As of September 2015, see http://autopublish.meteor.com. It's a system authored by @splendido that automatically publishes new versions of a wrapper package automatically on Atmosphere (once you've registered your repo with it), as soon as the upstream package has a new release. See the How it works page. For an example repo, see https://github.com/MeteorPackaging/numeraljs-core-wrapper.

The instructions from here on may be somewhat outdated.

Contribute (minimal effort)

1. If you're working on integrating a 3rd party library with Meteor, please post here. I have also reserved Meteor Developer (Atmosphere) organization namespaces for many libraries; ask if you need one.

2. If you have created an MD organization for a library, please let us know. Namespace is precious. Currently we're looking for:

   • angular
   • bootstrap
   • moment
   • famous
   • jade
   • foundation
   • highcharts
   • stripe
   • bitcoin
   • crypto
   • soundcloud
   • twilio (squatted and never used)
   • echo (squatted and never used)
   • win (for win.js)
   • app (for app.js)

   Who has these?

Popular libraries with official Meteor support

• ✅ d3 - [make, export file]
• ✅ Bootstrap Material Design by @FezVrasta. Use the PR as a template.
• ✅ Sortable [first merged!]
• ✅ Keypress [merged 2014-11-28]
• ✅ KeyboardJS [export file]
• ✅ summernote - WYSIWYG editor; [2014-11-28]
• ⌚ Semantic UI [discussion in progress]

PR acceptance pending

• 🕐 Mousetrap - keyboard events library [pending] [grunt, export file]
• 🕙 Font Awesome - [acknowledged]. Great example of Meteor resolving CSS URL paths correctly.
• ☑️ Moment [merged in develop, published]
• 🕐 Isotope [pending] [grunt, export file]
• 🕤 jsPlumb [pending, maintainer was in a pissed off mood today]
• 🕗 Hammer - multi-touch library, ~10k GitHub stars [pending, author has changed jobs] [grunt, export file]. Use it as a template.

Refused to accept the PR

• 🚫 keymaster
• 🚫 Bootstrap - with much love and offering a Tweet

How to do this

Overview

1. Post here asking @dandv and @splendido to add you to the MeteorPackaging organization and mention the library/libraries you want to package.
2. We'll fork the library's repo into MeteorPackacing and grant you access
3. Add the Meteor integration files,
   • package.js
   • tests
   • gruntfile (or makefile or equivalent) entries to run meteor publish
4. publish the package to Atmosphere yourself (this is very important)
5. submit a PR with the changes to the original library author (optional), or just notify them to get some exposure (they may offer to tweet about the integration or otherwise announce it)

Below are the detailed steps.

Get the integration working before even contacting the maintainer

1. Fork <repo_url_of_the_library>

2. git clone <your_fork_url>

3. cd <repo_directory>

4. git remote add upstream <repo_url_of_the_library>

5. git fetch upstream

6. Read through CONTRIBUTING.md or README.md and figure out which branch the original author wants pull requests against. Some can be very finicky.

7. git checkout -b meteor-integration upstream/that_branch

8. Create a meteor directory in the root of the project and copy there the Hammer.js Meteor package files, or the Font Awesome Meteor package files, depending on whether you integrate a library or CSS/image/font resources.

9. Go through every file and make changes to reflect the actual library you're working on.

   • in particular, give a GOOD summary in package.js (for SEO on Atmosphere), instead of the library's tagline. Example:

     Mousetrap is a simple library for handling keyboard shortcuts in Javascript.

     For Atmosphere, a repository of JavaScript libraries, this is suboptimal: it repeats the library name, and it says "library" and "JavaScript" (well duh). You only have 100 characters. Don't waste them. Better:

     "Mousetrap (official): bind, trigger and handle keyboard events on keys, combinations and sequences"

10. Export the library global(s)

    1. If the package is a jQuery package and adds itself to $, there's nothing to export.

    2. Otherwise, add a meteor/export.js file like this:

       /*global Hammer:true*/  // Meteor creates a file-scope global for exporting. This comment prevents a potential JSHint warning.
       Hammer = window.Hammer;
       delete window.Hammer;

11. Add a package test file, at least checking if the library instantiates correctly.

12. You want to make it as painless as possible for the maintainer to accept the PR. If there's a build process they use to publish, it would be great if you could add to it. Here's a gruntfile patch for Meteor and a Makefile patch (used for d3). If their README mentions Component/Bower/Npm, add a section mentioning Meteor (example).

13. Run the tests using the build process, e.g. grunt meteor-test. If you want to run tests manually, execute this:

    cp meteor/package.js .
    spacejam --mongo-url mongodb:// test-packages ./
    

Pick a namespace and publish the package under it

Please be very careful with this, as renaming packages is impossible.

Log into your Meteor Developer account and create an organization that represents the package. Most often it will be the name of library, without any special characters (no -, .). No need to include the JS part, since we're always dealing with JavaScript libraries.

If the organization name is not available, contact me, @dandv. I've registered a bunch of them, so potentially evil individuals don't :)

1. meteor publish the package to Atmosphere for the first time. This prevents the maintainer from running into an error that the package doesn't exist when they publish (meteor would complain about a --create flag).

2. After you've ensured publishing works (namespace is available, the name in package.js is valid etc.), push to your git fork:

   git commit
   git push origin meteor-integration
   

3. Congratulations! Reply to this issue and add the link to the package's Atmosphere page.

Now you can go to the GitHub page of the library and issue a pull request!

Contact the library maintainers

Here is the recommended PR message.

See d3 and Font Awesome above for addressing objections.

Contact the maintainers of other Meteor wrapper libraries

1. Ask them to deprecate the library by creating a PR overwriting the README.md of their package with the text

   This package is now deprecated. Please use the official Meteor integration package:
   
   http://atmospherejs.com/<org>/<package>
   

   The commit message should be "Deprecating package in favor of official integration".

   The name of the PR issue (after you click "Create pull request) should be "Kind request to deprecate package in favor of official integration".

   The text of the PR should be similar to this:

   Hi X,
   
   Thanks for publishing this package. In the meantime an
   [official Meteor integration](https://atmospherejs.com/<namespace>/<package>)
   has become available.
   
   Would you like to support the official package?
   
   If so, you can hide [your package](<atmosphere_link_to_their_package>)
   from Atmosphere searches, while still keeping it installable by apps and dependent
   packages, by running the following command:
   
       meteor admin set-unmigrated <their_full:package_name>
   
   Thank you,
   The [Meteor official integations team](https://github.com/raix/Meteor-community-discussions/issues/14)
   

2. Go to the Atmosphere page of their package and flag it anyway. Ideally, get others to flag the wrapper package. This is important because meteor doesn't warn the user when running meteor add on a deprecated package, so we hope users will check on Atmosphere. However, each package needs several flags from different users, in order to show as flagged globally.

TODO

• figure out namespacing exactly. Ideally we'd have an MD organization with the library name, and ask the library maintainers to create MD accounts reflecting their GitHub usernames. Problem:
  • sometimes the names are taken, e.g. moment (pinging @estark37)
  • sometimes the maintainer uses their name as the organization, and you can't have an org and individual with the same name on MD - e.g. RubaXa/Sortable
  • rarely, several libraries have the same name, e.g. RubaXa/Sortable and voidberg/html5sortable (contrived example, need a better one)

[gadicc]

@dandv, re 2, yeah, if there's no module framework found it exports to window. Which is bad for a Meteor package. It's easy to get around, but unfortunately requires extra files. e.g. chuangbo/meteor-marked@e55d9c2. Maybe part of this issue should be to either support that type of wrap policy natively or allow a { wrap: 'exports' } or something in addFiles.

[dandv]

@gadicc: how about just checking if Package is defined, and assigning to a global var?

[gadicc]

@dandv oh yeah sure, if you have access to the main package itself... forgot about that :> i mostly wrap git submodules, so don't like to touch the actual code. what you describe would work perfectly of course. have a vague memory though that Package name was used by something else too, not sure... it would solve our problems though :>

[PEM--]

👏

[dandv]

Today I'm happy to present the official d3 integration.

Please log into Atmosphere with your MD account and,

• star https://atmospherejs.com/d3js/d3
• flag https://atmospherejs.com/meteor/d3

Thanks!

[raix]

@dandv cool - is it the d3js or meteor that maintains the package?

[dandv]

@raix: the best permissions combo I've found so far was to create an organization for the library, add myself to it so I can publish the package (helps to remove barriers for the maintainer and make it as easy as possible for them), then ask them to sign up for an MD at meteor.com and tell me their username. Really a 30-second process. Then I'll add their username to the org so they can meteor publish as well.

[raix]

@dandv that makes sense - it would be nice if possible to add the package.js in their repo (the underscore already got 3 package configs... would be nice with just one...)