meteor/cosmos-browserify

Name: cosmos-browserify

Owner: Meteor

Description: Browserify npm modules for client side in Meteor packages

Forked from: elidoran/cosmos-browserify

Created: 2015-06-17 21:44:39.0

Updated: 2015-06-17 21:44:39.0

Pushed: 2015-06-23 02:21:01.0

Homepage:

Size: 181

Language: CoffeeScript

GitHub Committers

UserMost Recent Commit# Commits

Other Committers

UserEmailMost Recent Commit# Commits

README

Cosmos Browserify Build Status

Browserify npm dependencies in Meteor packages for client side use.
Table of Contents
  1. Example Meteor App
  2. Use in a Meteor Package
    1. Create and Add Your Package
    2. Create browserify file
    3. Update package.js
    4. Verify success
    5. Use Variable
  3. Use in a Meteor App
    1. Enable App npm modules
    2. Create App browserify file
    3. Enable browserify
    4. Verify success
  4. Passing options to Browserify
    1. Using transforms
Example Meteor App

Look at cosmos-browserify-example for a complete working Meteor app example. Look at a package in the app to see how to make one.

Use in a Meteor Package

Specify npm modules in your package and browserify them to the client. The variables may be package scoped or app (global) scoped.

Quick Start

For a quick start, copy my functional example package.

1. Create and Add your package

Use standard Meteor package create and add:

teor create --package cosmos:browserify-example
teor add cosmos:browserify-example
2. Create browserify file

Create a JavaScript file requiring the npm modules you want to browserify. The file name must end with browserify.js. NOTE: Due to Meteor Issue #3985 we must put something before the extension, like: client.browserify.js. Example content:

ithout var it becomes a package scoped variable
rcase = require('upper-case');
3. Update package.js
pecify npm modules
depends({
pper-case':'1.1.2'


age.onUse(function(api) {
 add package
i.use(['cosmos:browserify@0.2.0'], 'client');

 add browserify file in step #2 with your package's client files
i.addFiles(['client.browserify.js', 'your/package/file.js'], 'client');

 OPTIONAL: make variable app (global) scoped:
i.export('uppercase', 'client');

Exporting to app

As with all other variables in a package the browserified variables are limited to the package scope unless they are exported via api.export() as shown above.

4. Verify success

First, ensure your app is running without errors.

App scoped variable

If you exported a variable to the app scope then you may use it in the browser's JavaScript console.

Package scoped variable

If your variable is package scoped you may still verify it was browserified.

A. Use View Source to see the script tags Meteor is sending to your client.

B. Find your package's script tag and click on it to view its source. For package someuser:somepackage there will be a script tag like this:

ipt type="text/javascript" src="/packages/someuser_somepackage.js?a5c324925e5f6e800a4"></script>

C. Find your package's browserify script. If your package was someuser:somepackage and the file named client.browserify.js then you'd look for a block like this:

////////////////////////////////////////////////////
ackages/someuser:somepackage/client.browserify.js //
////////////////////////////////////////////////////

D. Ensure the variable you want is in the package scoped area. If you're looking for a variable named uppercase then you'd see this:

ackage-scope variables */
uppercase, __coffeescriptShare;

Note: I always use coffeescript, so there's always the __coffeescriptShare there. I'm not sure if it's always there or not.

5. Use variable

In your package's client scripts you have access to all package scoped variables, including those browserified. For example:

ole.log("uppercase('some text') = ", uppercase('some text'));
Use in a Meteor App

Specify npm modules in your app and browserify them to the client. The variables will be app (global) scoped.

It is possible to make browserified variables app (global) scoped by exporting them from a package with api.export(). Please see Exporting to App.

1. Enable app npm modules

Meteor doesn't support npm modules at the app level. Fortunately, you can add the ability with the meteorhacks:npm package.

teor add meteorhacks:npm

The first time your app runs (or if it's running when you add the package) it will create a packages.json file in the root of your app. Specify the modules in packages.json. For example:


pper-case" : "1.1.2"

2. Create app browserify file

Create a JavaScript file requiring the npm modules you want to browserify. The name must end with browserify.js. NOTE: Due to Meteor Issue #3985 we must put something before the extension, like: app.browserify.js. For example:

ithout var it becomes an app (global) scoped variable
rcase = require('upper-case');
3. Enable browserify

Add cosmos:browserify:

teor add cosmos:browserify

It will browserify your app.browserify.js file and push it to the client.

4. Verify it worked

In your browser's JavaScript console you can use the variable (uppercase if you followed my example).

Passing options to Browserify

Browserify can be configured with additional options by adding a file with the same name as your .browserify.js file, but with the extension .browserify.options.js.

ample file structure:
p.browserify.js           # entry point
p.browserify.options.js   # options

You can use any options that you can pass to the API.

Using transforms

To use a Browserify transform from NPM, add its package to your packages.json as described above; then pass it in the special transform option. This option is an object where the keys are the transform names, and the values are the options that can be passed to that transform.

Below is an example of using the exposify transform to use a global React variable with React Router instead of the React package from NPM.

packages.json

eact-router": "0.13.3",
xposify": "0.4.3"

app.browserify.js
tRouter = require("react-router");
app.browserify.options.json

ransforms": {
"exposify": {
  "global": true,
  "expose": {
    "react": "React"
  }
}


Transforms in a Package

Make Meteor watch the options file for updates by adding it to the API:

rom example package in cosmos-browserify-example
addFiles([
'client/example.html',    // show some example results
'client/example.coffee',  // package's Meteor script
'client.browserify.js',           // browserify file
'client.browserify.options.json'  // browserify options file

lient'

MIT License

This work is supported by the National Institutes of Health's National Center for Advancing Translational Sciences, Grant Number U24TR002306. This work is solely the responsibility of the creators and does not necessarily represent the official views of the National Institutes of Health.