vulcanize
v1.16.0
Published
Process Web Components into one output file
Downloads
15,391
Readme
Vulcanize
Reduce an HTML file and its dependent HTML Imports into one file
Named for the Vulcanization process that turns polymers into more durable materials.
Web pages that use multiple HTML Imports 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 Vulcanize tool follows HTML Imports and <script>
tags to inline these external assets into a single page, 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 vulcanize for production uses.
Installation
vulcanize
is available on npm. For maximium utility, vulcanize
should be installed globally.
npm install -g vulcanize
This will install vulcanize
to /usr/local/bin/vulcanize
(you may need sudo
for this step).
Options
-h
|--help
: print this message-v
|--version
: print version number-p <arg>
|--abspath <arg>
: use as the "webserver root", make all adjusted urls absolute--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
--strip-exclude
: Exclude a subpath and remove any links referencing it.--inline-scripts
: Inline external scripts.--inline-css
: Inline external stylesheets.--add-import <path>
: Add this import to the target HTML before vulcanizing. Can be used multiple times.--redirect <uri>|<path>
: Takes an argument in the form of URI|PATH where url is a URI composed of a protocol, hostname, and path and PATH is a local filesystem path to replace the matched URI part with. Multiple redirects may be specified; the earliest ones have the highest priority.--strip-comments
: Strips all HTML comments not containing an @license from the document.--no-implicit-strip
: DANGEROUS! Avoid stripping imports of the transitive dependencies of imports specified with--exclude
. May result in duplicate javascript inlining.--out-html <path>
: If specified, output will be written to instead of stdout.--out-request-list <path>
: Writes a list of request URLs required to vulcanize to on success.
Usage
The command
vulcanize target.html
will inline the HTML Imports of target.html
and print the resulting HTML to
standard output.
The command
vulcanize target.html > build.html
will inline the HTML Imports of target.html
and print the result to
build.html
.
The command
vulcanize -p "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
vulcanize --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
.
If the --strip-exclude
flag is used, the HTML Import <link>
tags that
point to resources in path/totarget/subpath
and path/to/target/subpath2/
will also be removed.
The command
vulcanize --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
vulcanize --inline-css target.html
will inline Polymerized stylesheets, <link rel="import" type="css">
The command
vulcanize --strip-comments target.html
will remove HTML comments, except for those that begin with @license
.
License comments will be deduplicated.
Using vulcanize programmatically
Vulcanize as a library has two exported function.
vulcanize
constructor takes an object of options similar to the command line
options.
abspath
: A folder to treat as "webroot".- When specified, use an absolute path to
target
.
- When specified, use an absolute path to
excludes
: An array of strings with regular expressions to exclude paths from being inlined.stripExcludes
: Similar toexcludes
, but strips the imports from the output entirely.- If
stripExcludes
is empty, it will be set the value ofexcludes
by default.
- If
inlineScripts
: Inline external scripts.inlineCss
: Inline external stylesheets.addedImports
: Additional HTML imports to inline, added to the end of the target fileredirects
: An array of strings with the formatURI|PATH
where url is a URI composed of a protocol, hostname, and path and PATH is a local filesystem path to replace the matched URI part with. Multiple redirects may be specified; the earliest ones have the highest priority.stripComments
: Remove non-license HTML comments.inputUrl
: A URL string that will override thetarget
argument tovulcanize.process()
. By design, gulp and grunt plugins expect to work on the given file path.vulcanize
has its own file loader, and expects to be given URLs. In instances where the filename cannot be used as a URLinputUrl
will override the filename.loader
: A hydrolysis loader. This loader is generated with thetarget
argument tovulcan.process
and theexclude
paths. A custom loader can be given if more advanced setups are necesssary.
vulcanize.process
takes a target
path to target.html
and a callback.
Example:
var Vulcanize = require('vulcanize');
var hydrolysis = require('hydrolysis');
/* a Hydrolysis loader object (optional) */
var loader = new hydrolysis.loader(...)
var vulcan = new Vulcanize({
abspath: '',
excludes: [
'\\.css$'
],
stripExcludes: [
],
inlineScripts: false,
inlineCss: false,
addedImports: [
],
redirects: [
],
implicitStrip: true,
stripComments: false
// optional
loader: loader,
inputUrl: ''
});
vulcan.process(target, function(err, inlinedHtml) {
});
Caveats
Because HTML Imports changes the order of execution scripts can have, Vulcanize has to make a few compromises to achieve that same script execution 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.
What happened to [feature] from 0.X?
--csp
mode has been moved into crisper--strip
mode was removed, use something like html-minifier or minimize- Use these at your own risk, they may not understand all of Polymer's uses of HTML or CSS (https://github.com/kangax/html-minifier/issues/377)