Need help with gulp-umd?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

eduardolundgren
125 Stars 15 Forks MIT License 48 Commits 12 Opened issues

Description

Gulp plugin for build JavaScript files as Universal Module Definition, aka UMD

Services available

!
?

Need anything else?

Contributors list

# 8,037
JavaScr...
jira
jQuery
HTML
18 commits
# 90,348
qrcode
Go
golang
Shell
15 commits
# 181,593
CSS
HTML
data-bi...
knockou...
3 commits
# 22,872
reactjs
TeX
coercio...
Node.js
1 commit
# 324,111
HTML
Shell
TypeScr...
avro
1 commit
# 1,051
TypeScr...
React
react-c...
Redux
1 commit
# 47,895
Shell
laravel...
laravel...
email-v...
1 commit
# 187,841
Sass
nextjs
gatsby-...
Storybo...
1 commit

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 = '
}
  • dependencies
    : Function which returns an array of dependencies. Each dependency is specified either as a string, or as an object of the form.
    js
    {
    dependencies: function (file) {
      return {
        name: 'defaultModuleName',
        amd: 'moduleNameInAMD',
        cjs: 'moduleNameInCommonJsAndNodeJs',
        global: 'moduleNameInBrowserGlobals',
        param: 'ModuleIdentifier'
      }
    }
    
  • exports
    : Specifies the item (or for CommonJS, item's) which the module will export. For non CommonJS, this value should be a string specifying the exported item.
    js
    {
    exports: function (file) {
      return 'Foo.Bar';
    }
    }
    
    For CommonJS, this value should be an object with keys specifying the names and values specifying the exported items.
    js
    {
    exports: function (file) {
      return {
        'Foo': 'Foo',
        'FooBar': 'Foo.Bar'
      };
    }
    }
    
  • namespace
    : Specifies the global namespace to export to. Only used for Web globals.
    js
    {
    namespace: function (file) {
      return 'My.Global.Namespace';
    }
    }
    
  • templateName
    : Specifies the name of the template to use. Available template names are amd, amdNodeWeb, amdCommonWeb, amdWeb, common, node, returnExports and web. See above for descriptions. If specified, overrides the template and templateSource.
    js
    {
    templateName: 'amdNodeWeb'
    }
    
  • templateSource
    : Specifies the lodash template source to use when wrapping input files. If specified, overrides template.
    js
    {
    template: ''
    }
    
  • template
    : Specifies the path to a file containing a lodash template to use when wrapping input files.
    {
    template: '/path/to/my/template'
    }
    

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:

  • : Contains the AMD normalized values from the options dependencies array, e.g. 
    ['a', 'b']
    turns into
    ['a', 'b']
    .
  • : Contains the CommonJS normalized values from the options dependencies array, e.g. 
    ['a', 'b']
    turns into
    require('a'), require('b')
    .
  • : As above, prefixed with ', ' if not empty.
  • : Contains the browser globals normalized values from the options dependencies array, e.g. 
    ['a', 'b']
    turns into
    root.a, root.b
    .
  • : As above, prefixed with ', ' if not empty.
  • : The namespace where the exported value is going to be set on the browser, e.g. 
    root.Foo.Bar
    .
  • : What the module should return, e.g. 
    Foo.Bar
    . By default it returns the filename with uppercase without extension, e.g.
    foo.js
    returns
    Foo
    . If using CommonJS, this value may be an object as specified by the result of options.exports
  • : Comma seperated list of variable names which are bound to their respective modules, eg 
    a, b
    .
  • : As above, prefixed with ', ' if not empty.

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.