Home

Awesome

gulp-umd

Build Status

This repository provides a simple way to build your files with support for the design and implementation of the Universal Module Definition (UMD) API for JavaScript modules. These are modules which are capable of working everywhere, be it in the client, on the server or elsewhere.

The UMD pattern typically attempts to offer compatibility with the most popular script loaders of the day (e.g RequireJS amongst others). In many cases it uses AMD as a base, with special-casing added to handle CommonJS compatibility.

Variations

Regular Module

See more variation options that can be added as templates onto this project on the UMD (Universal Module Definition) patterns.

Options

The following options are the ones available with the current default values:

{
  dependencies: function(file) {
    return [];
  },
  exports: function(file) {
    return capitalizeFilename(file);
  },
  namespace: function(file) {
    return capitalizeFilename(file);
  },
  templateName: 'amdNodeWeb',
  template: path.join(__dirname, 'templates/returnExports.js'),
  templateSource: 'module.exports = <%= exports %>'
}

Examples

Build a simple module

Let's wrap src/foo.js file with UMD definition:

'use strict';
function Foo() {}

Then, in the gulp task:

gulp.task('umd', function() {
  return gulp.src('src/*.js')
    .pipe(umd())
    .pipe(gulp.dest('build'));
});

After build build/foo.js will look like:

(function(root, factory) {
  if (typeof define === 'function' && define.amd) {
    define([], factory);
  } else if (typeof exports === 'object') {
    module.exports = factory();
  } else {
    root.Foo = factory();
  }
}(this, function() {
'use strict';
  function Foo() {}
  return Foo;
}));

Note that by default the filename foo.js is uppercased and will be used as the return exports for your module and also for the global namespace, in this case root.Foo. This is configurable, see the advanced build section below.

Build with dependencies

Let's wrap src/foo.js file with UMD definition defining some dependencies:

'use strict';
function Foo() {}

Then, in the gulp task:

gulp.task('umd', function(file) {
  return gulp.src('src/*.js')
    .pipe(umd({
        dependencies: function(file) {
          return [
            {
              name: 'moduleName1',
              amd: 'moduleName1_amd',
              cjs: 'moduleName1_cjs',
              global: 'moduleName1_glob',
              param: 'moduleName1'
            },
            {
              name: 'moduleName2',
              amd: 'moduleName2_amd',
              cjs: 'moduleName2_cjs',
              global: 'moduleName2_glob',
              param: 'moduleName2'
            }
          ];
        }
      }))
    .pipe(gulp.dest('build'));
});

After build build/foo.js will look like:

(function(root, factory) {
  if (typeof define === 'function' && define.amd) {
    define(['moduleName1_amd', 'moduleName2_amd'], factory);
  } else if (typeof exports === 'object') {
    module.exports = factory(require('moduleName1_cjs'), require('moduleName2_cjs'));
  } else {
    root.Foo = factory(root.moduleName1_glob, root.moduleName2_glob);
  }
}(this, function(moduleName1, moduleName2) {
'use strict';
  function Foo() {}
  return Foo;
}));

The advanced configuration for the dependencies allows you to have full control of how your UMD wrapper should handle dependency names.

Advanced build

Let's wrap src/foo.js file with UMD definition and exports the Foo.Bar class:

'use strict';
function Foo() {};
Foo.Bar = function() {};

Then, in the gulp task:

gulp.task('umd', function() {
  return gulp.src('src/*.js')
    .pipe(umd({
      exports: function(file) {
          return 'Foo.Bar';
        },
        namespace: function(file) {
          return 'Foo.Bar';
        }
    }))
    .pipe(gulp.dest('build'));
});

After build `build/foo.js will look like:

(function(root, factory) {
  if (typeof define === 'function' && define.amd) {
    define([], factory);
  } else if (typeof exports === 'object') {
    module.exports = factory();
  } else {
    root.Foo.Bar = factory();
  }
}(this, function() {
'use strict';
  function Foo() {};
  Foo.Bar = function() {};
  return Foo.Bar;
}));

Templates

In order to use any of the variations defined on the UMD (Universal Module Definition) patterns repository you can use the following template keys:

You can also use umd-templates, using the patternName.path property if template option is used, and patternName.template if templateSource is used.

Contributing

  1. Fork it!
  2. Create your feature branch: git checkout -b my-new-feature
  3. Commit your changes: git commit -m 'Add some feature'
  4. Push to the branch: git push origin my-new-feature
  5. Submit a pull request :D