grunt-requirejs-auto-bundles
Automated shared bundles for grunt-contrib-requirejs.
This task automatically updates and optimizes your modules:
config for
RequireJS optimizer builds.
This means you can create projects that have multiple "main" or "entry"
modules, but also easily have all common modules placed into bundles to reduce
total download for your users.
This leaves you the freedom to focus on setting your module dependencies
accurately, instead of optimally for your builds.
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-requirejs-auto-bundles --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile
with this line of JavaScript:
grunt.loadNpmTasks('grunt-requirejs-auto-bundles');
The "autobundles" task
Overview
This task reads your requirejs.config()
and your grunt-contrib-requirejs
build config, figures out the contents of the shared bundles, then updates your
modules:
config for your requirejs
task (it won't produce the final build).
Therefore, it is advised to begin with grunt-contrib-requirejs
and get that
working with the dir:
and modules:
options for its requirejs
task.
Then, in your project's Gruntfile, add a section named autobundles
to the
data object passed into grunt.initConfig()
.
grunt.initConfig({
autobundles: {
your_target: {
maxBundles: 3,
requireConfigModule: 'require-config'
},
},
requirejs: {
your_target: {
appDir: 'path/to/app',
baseUrl: './',
dir: 'path/to/build',
modules: [
{ name: 'require-config' },
{ name: 'main-a' },
{ name: 'main-b' }
]
}
}
});
Then, you should configure your build task to first run autobundles
before
requirejs
:
grunt.registerTask('build', ['autobundles', 'requirejs']);
Options
options.maxBundles
Type: Number
Default value: 3
The maximum number of bundles that any main module should have to fetch. A
smaller number will mean fewer HTTP requests, but larger total download size
due to bundling uncommon modules. You may want to test different values to
find the right balance for your project.
options.requireConfigModule
Type: String
Default value: 'require-config'
The module ID for the JS file that calls requirejs.config({ ... })
. This
should match an entry in the modules:
task config for requirejs
.
Usage Examples
In addition to the example task configuration above, you're expected to setup
your project like so:
Contents of require-config.js
:
requirejs.config({
});
In your HTML, you'll need to load your require-config.js
first, then your
"main" module.
When in development, you'll want to do something like this:
<script src="/src/require.js"></script>
<script>
require.config({
baseUrl: '/src'
});
require(['require-config'], function() {
require(['main-a']);
});
</script>
When in production, you'll want to change the paths to point to the build dir
as specified by the dir:
setting for requirejs
:
<script src="/build/require.js"></script>
<script>
require.config({
baseUrl: '/build'
});
require(['require-config'], function() {
require(['main-a']);
});
</script>
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
(Nothing yet)