grunt-front-end-modules

Use npm to manage front-end dependencies

Getting Started

This plugin requires Grunt ~0.4.5

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-front-end-modules --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-front-end-modules');

The "front_end_modules" task

This task allows you to use npm to manage front-end dependencies on your project. It will copy files out of installed packages to other areas of your project such as a libs directory. It was inspired by this vision of npm and front-end packaging.

It will honor the file specified in the main key in a dependent module's package.json or you can configure a package specific key. You can also exercise full control over what files are copied via the gruntjs file configuration formats.

This task could be run as a postinstall script or as part of your existing grunt workflow. For CommonJS modules, you can then use a solution like browserify to make those modules runnable in a browser.

Overview

In your project's Gruntfile, add a section named front_end_modules to the data object passed into grunt.initConfig().

grunt.initConfig({
  front_end_modules: {
    options: {
      dest: 'js/libs'
    },
    libs: {
      modules: [
        'underscore',
        'mustache'
      }
    },
    test: {
      options: {
        dest: 'test/libs'
      },
      modules: [
        'jasmine-jquery'
      }
    },
    'cactus': {
      src: 'dist/foo.js',
      dest: 'js/libs'
    }
  },
});

The specified front-end module files will be copied from node_modules to the destination path. Modules that are published in CommonJs format can be converted using browserify.

Options

options.dest

Type: String Default value: none

A string value that specifies the destination directory to copy modules to.

options.moduleSrcKey

Type: String Default value: none

A string value that specifies the field in the module's package.json to use for the module file or list of files to copy to options.dest.

options.browserify

Type: Object Default value: none

grunt-browserify configuration that is passed directly to grunt-browserify as its options.

Usage Examples

There are several ways to specify front-end module dependencies to be copied. All modules must be installed under node_modules.

Multiple Modules

You can copy multiple front-end modules. Each module will have its main file as configured in the main property of its package.json copied to the options.dest path. Configure different targets for each destination path.

grunt.initConfig({
  front_end_modules: {
    libs: {
      options: {
        dest: 'js/libs'
      },
      modules: [
        'underscore',
        'mustache'
      }
    },
    test: {
      options: {
        dest: 'test/libs'
      },
      modules: [
        'jasmine-jquery'
      }
    }
  },
});

In the example above, underscore.js and mustache.js will be copied from their installed packages under node_modules to js/libs, and jasmine-jquery.js will be copied from its installed package to test/libs.

Single Module

You can copy a single front-end module by using the package name as the target name. Its main file as configured in the main property of its package.json will be copied to the options.dest path. The name of the task target is the name of the npm package.

grunt.initConfig({
  front_end_modules: {
    underscore: {
      options: {
        dest: 'js/libs/underscore'
      }
    },
    mustache: {
      options: {
        dest: 'js/libs/mustache'
      }
    }
  }
});

In the example above, underscore.js will be copied from its installed package under node_modules to js/libs/underscore, and mustache.js will be likewise be copied from its installed package to js/libs/mustache.

Package Specific Key for Main Files

If a package uses a key other than main in its package.json say for example to specify a collection of library files, that key can be configured under options.moduleSrcKey. The name of the task target is the name of the npm package.

grunt.initConfig({
  front_end_modules: {
    options {
      dest: 'js/libs'
    }
    cactus: {
      options: {
        moduleSrcKey: 'srcFiles'
      }
    }
  }
});

In the example above, a library named cactus in node_modules/cactus will have the file or files specified in the srcFiles key of its package.json copied to js/libs.

Package Specific Files

For fine-grained control over which modules files are copied all gruntjs file configuration formats are also supported on a per target basis. The name of the task target is the name of the npm package.

grunt.initConfig({
  front_end_modules: {
    'cactus': {
      src: 'dist/**/*.js',
      dest: 'js/libs'
    }
  },
});

In the example above, all .js files under node_modules/cactus/dist will be copied to js/libs.

Browserify CommonJS-Style Files

If the module you are using is written in the CommonJS-Style, you can run browserify directly instead of just copying the modules files. Just add a browserify section to the task configuration which will become the options configuration passed to grunt-browserify. The name of the task target is the name of the npm package. If you omit the src field, the main file of the package will be used. If you omit, the dest file, the name of the main file will be used. If you supply a dest filename, the dest path will be prefixed to the filename.

grunt.initConfig({
  front_end_modules: {
    options: {
      dest: 'js/libs'
    },
    semver: {
      browserify: {
        browserifyOptions: {
          standalone: 'semver'
        }
      }
    },
    'underscore.string': {
      browserify: {
        browserifyOptions: {
          standalone: 'underscore.string'
        }
      },
      dest: 'underscore.string.js'
    }
  }
});

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

• 1.1.0 Initial version
• 1.2.0 Add built-in browserify support