Polymer Bundler
polymer-bundler is a library for packaging project assets for production to minimize network round-trips.
Relationship to Polymer CLI
The Polymer CLI uses polymer-build, which uses polymer-bundler, so you can think of the CLI's build pre-configured polymer-build pipeline including polymer-bundler. Setting this up for you makes the CLI easy to use, but as a command-line wrapper its customization options are more limited. polymer-bundler allows you to completely customize your bundle strategy.
Usage
Web pages that use multiple HTML Imports, external scripts, and stylesheets to load dependencies may end up making lots of network round-trips. In many cases, this can lead to long initial load times and unnecessary bandwidth usage. The polymer-bundler tool follows HTML Imports, external script and stylesheet references, inlining these external assets into "bundles", to be used in production.
In the future, technologies such as HTTP/2 and Server Push will likely obsolete the need for a tool like polymer-bundler for web deployment uses.
Installation
polymer-bundler
is available on npm. For maximium utility, polymer-bundler
should be installed globally.
npm install -g polymer-bundler
This will install polymer-bundler
to /usr/local/bin/polymer-bundler
(you may need sudo
for this step).
Options
-h
|--help
: Print this message-v
|--version
: Print version number-r
|--root
: The root of the package/project being bundled. Defaults to the current working folder.--exclude <path>
: Exclude a subpath from root. Use multiple times to exclude multiple paths. Tags (imports/scripts/etc) that reference an excluded path are left in-place, meaning the resources are not inlined. ex: --exclude=elements/x-foo.html --exclude=elements/x-bar.html
--inline-scripts
: External scripts will only be inlined if this flag is provided.--inline-css
: External stylesheets will only be inlined if this flag is provided.--manifest-out <path>
: If specified, the bundle manifest will be written out to <path>
.--redirect <prefix>|<path>
: Routes URLs with arbitrary <prefix>
, possibly including a protocol, hostname, and/or path prefix to a <path>
on local filesystem. For example --redirect "myapp://|src"
would route myapp://main/home.html
to ./src/main/home.html
. Multiple redirects may be specified; the earliest ones have the highest priority.--rewrite-urls-in-templates
: Fix URLs found inside <style>
tags and certain element attributes (action
, assetpath
, href
, src
, and style
) when inside <template>
tags. This may be necessary to bundle some Polymer 1.x projects with components that ues relative image URLs in their styles, as Polymer 1.x did not use the assetpath
of <dom-module>
to resolve URLs in styles like Polymer 2.x does.--shell
: Uses a bundling strategy which puts inlines shared dependencies into a specified html app "shell".--strip-comments
: Strips all HTML comments from the document which do not contain an @license
, or start with <!--#
or <!--!
.--sourcemaps
: Honor (or create) sourcemaps for inline script tags.--out-file <path>
: If specified, output will be written to instead of stdout.--out-dir <path>
: If specified, output will be written to . Necessary if bundling multiple files.
Usage
The command
polymer-bundler target.html
will inline the HTML Imports of target.html
and print the resulting HTML to standard output.
The command
polymer-bundler target.html --rewrite-urls-in-templates
will inline the HTML Imports of target.html
and rewrite relative URLs encountered in style tags and element attributes to support Polymer 1.x projects which may rely on it.
The command
polymer-bundler target.html > build.html
will inline the HTML Imports of target.html
and print the result to build.html
.
The command
polymer-bundler -r "path/to/target/" /target.html
will inline the HTML Imports of target.html
, treat path/to/target/
as the webroot of target.html, and make all URLs absolute to the provided webroot.
The command
polymer-bundler --exclude "path/to/target/subpath/" --exclude "path/to/target/subpath2/" target.html
will inline the HTML Imports of target.html
that are not in the directory path/to/target/subpath
nor path/to/target/subpath2
.
The command
polymer-bundler --inline-scripts target.html
will inline scripts in target.html
as well as HTML Imports. Exclude flags will apply to both Imports and Scripts.
The command
polymer-bundler --inline-css target.html
will inline Polymerized stylesheets, <link rel="import" type="css">
The command
polymer-bundler --strip-comments target.html
will remove HTML comments, except for those containing @license
or starting with <!--#
or <!--!
. License comments will be deduplicated.
The command
polymer-bundler --redirect "myapp://|src" target.html
will route all URLs with prefix myapp://
to the src
folder. So a URL like myapp://main/index.html
would actually resolve to a file in ./src/main/index.html
relative to the package root.
Using polymer-bundler programmatically
polymer-bundler as a library has two exported function.
polymer-bundler
constructor takes an object of options similar to the command line options:
analyzer
: An instance of polymer-analyzer
which provides analysis of and access to files to bundle. Bundler will create its own instance if this is not given.excludes
: URLs to exclude from inlining. URLs may represent files or folders. HTML tags referencing excluded URLs are preserved.sourcemaps
: Honor (or create) sourcemaps for inline scriptsinlineCss
: Will inline content of external stylesheets into the bundle html. Defaults to true
.inlineScripts
: Inline content of external scripts into the bundled html. Defaults to true
.rewriteUrlsInTemplates
: Fix URLs found inside <style>
tags and certain element attributes (action
, assetpath
, href
, src
, and style
) when inside <template>
tags. This may be necessary to bundle some Polymer 1.x projects with components that ues relative image URLs in their styles, as Polymer 1.x did not use the assetpath
of <dom-module>
to resolve URLs in styles like Polymer 2.x does. Defaults to false
.sourcemaps
: Honor (or create) sourcemaps for inline scripts. Defaults to false
.stripComments
: Remove all HTML comments, except for @license
, which are merely de-duplicated, server-side include directives like <!--# ... -->
, and other important comments of the form <!--! ... -->
. Defaults to false
.strategy
: A function that takes an array of bundles and returns an array of bundles. There are a strategy factory functions available in bundle-manifest.urlMapper
: A function that takes bundles and returns a Map of URLs to bundles. This determines the location of generated bundles. There are URL mapper factory functions available in bundle-manifest
.generateManifest()
takes a collection of entrypoint URLs and promises a BundleManifest
which describes all the bundles it will produce.
.bundle()
takes a BundleManifest
and returns a Promise
for a BundleResult
, which contains a map of the generated bundle html files and an updated manifest containing information on what imports were inlined for each Bundle
.
A simple example:
const bundler = new require('polymer-bundler').Bundler();
bundler.generateManifest(['my-app.html']).then((manifest) => {
bundler.bundle(manifest).then((result) => {
console.log('<!-- BUNDLED VERSION OF my-app.html: -->');
console.log(result.documents.get('my-app.html').content);
});
});
An example with a customized sharding strategy and output layout:
const {Analyzer, FsUrlLoader} = require('polymer-analyzer');
const analyzer = new Analyzer({
urlLoader: new FsUrlLoader(path.resolve('.'))
});
const {Bundler,
generateSharedDepsMergeStrategy,
generateCountingSharedBundleUrlMapper} = require('polymer-bundler');
const bundler = new Bundler({
analyzer: analyzer,
excludes: [],
inlineScripts: true,
inlineCss: true,
rewriteUrlsInTemplates: false,
stripComments: true,
strategy: generateSharedDepsMergeStrategy(3),
urlMapper: generateCountingSharedBundleUrlMapper('shared/bundle_')
});
bundler.generateManifest(['item.html', 'cart.html']).then((manifest) => {
bundler.bundle(manifest).then((result) => {
});
});
Caveats
In order to inlining the contents of HTML Import documents into the bundle, polymer-bundler
has to make a few compromises to preserve valid HTML structure, script execution and style rule order:
-
Contents of all HTML Import documents will be moved to <body>
-
Any scripts or styles, inline or linked, which occur after a <link rel="import">
node in <head>
will be moved to <body>
after the contents of the HTML Import.