| 1 | [](https://npmjs.org/package/vulcanize)
|
| 2 | [](https://travis-ci.org/Polymer/vulcanize)
|
| 3 |
|
| 4 | # Vulcanize
|
| 5 |
|
| 6 | ### Reduce an HTML file and its dependent HTML Imports into one file
|
| 7 |
|
| 8 | >Named for the [Vulcanization](http://en.wikipedia.org/wiki/Vulcanization) process that turns polymers into more durable
|
| 9 | materials.
|
| 10 |
|
| 11 | Web pages that use multiple [HTML Imports](http://www.html5rocks.com/en/tutorials/webcomponents/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.
|
| 12 |
|
| 13 | In the future, technologies such as [HTTP/2](http://en.wikipedia.org/wiki/HTTP/2) and [Server Push](https://http2.github.io/faq/#whats-the-benefit-of-server-push) will likely obsolete the need for a tool like vulcanize for production uses.
|
| 14 |
|
| 15 | ## Installation
|
| 16 |
|
| 17 | `vulcanize` is available on npm. For maximium utility, `vulcanize` should be installed globally.
|
| 18 |
|
| 19 | npm install -g vulcanize
|
| 20 |
|
| 21 | This will install `vulcanize` to `/usr/local/bin/vulcanize` (you may need `sudo`
|
| 22 | for this step).
|
| 23 |
|
| 24 | ## Options
|
| 25 | - `-h`|`--help`: print this message
|
| 26 | - `-v`|`--version`: print version number
|
| 27 | - `-p <arg>`|`--abspath <arg>`: use <arg> as the "webserver root", make all adjusted urls absolute
|
| 28 | - `--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`
|
| 29 | - `--strip-exclude`: Exclude a subpath and remove any links referencing it.
|
| 30 | - `--inline-scripts`: Inline external scripts.
|
| 31 | - `--inline-css`: Inline external stylesheets.
|
| 32 | - `--add-import <path>`: Add this import to the target HTML before vulcanizing. Can be used multiple times.
|
| 33 | - `--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.
|
| 34 | - `--strip-comments`: Strips all HTML comments not containing an @license from the document.
|
| 35 | - `--no-implicit-strip`: *DANGEROUS*! Avoid stripping imports of the transitive dependencies of imports specified with `--exclude`. May result in duplicate javascript inlining.
|
| 36 | - `--out-html <path>`: If specified, output will be written to <path> instead of stdout.
|
| 37 | - `--out-request-list <path>`: Writes a list of request URLs required to vulcanize <html file> to <path> on success.
|
| 38 |
|
| 39 | ## Usage
|
| 40 | The command
|
| 41 |
|
| 42 | vulcanize target.html
|
| 43 |
|
| 44 | will inline the HTML Imports of `target.html` and print the resulting HTML to
|
| 45 | standard output.
|
| 46 |
|
| 47 | The command
|
| 48 |
|
| 49 | vulcanize target.html > build.html
|
| 50 |
|
| 51 | will inline the HTML Imports of `target.html` and print the result to
|
| 52 | `build.html`.
|
| 53 |
|
| 54 | The command
|
| 55 |
|
| 56 | vulcanize -p "path/to/target/" /target.html
|
| 57 |
|
| 58 | will inline the HTML Imports of `target.html`, treat `path/to/target/` as the
|
| 59 | webroot of target.html, and make all urls absolute to the provided webroot.
|
| 60 |
|
| 61 | The command
|
| 62 |
|
| 63 | vulcanize --exclude "path/to/target/subpath/" --exclude "path/to/target/subpath2/" target.html
|
| 64 |
|
| 65 | will inline the HTML Imports of `target.html` that are not in the directory
|
| 66 | `path/to/target/subpath` nor `path/to/target/subpath2`.
|
| 67 |
|
| 68 | If the `--strip-exclude` flag is used, the HTML Import `<link>` tags that
|
| 69 | point to resources in `path/totarget/subpath` and `path/to/target/subpath2/`
|
| 70 | will also be removed.
|
| 71 |
|
| 72 | The command
|
| 73 |
|
| 74 | vulcanize --inline-scripts target.html
|
| 75 |
|
| 76 | will inline scripts in `target.html` as well as HTML Imports. Exclude flags will apply to both Imports and Scripts.
|
| 77 |
|
| 78 | The command
|
| 79 |
|
| 80 | vulcanize --inline-css target.html
|
| 81 |
|
| 82 | will inline Polymerized stylesheets, `<link rel="import" type="css">`
|
| 83 |
|
| 84 | The command
|
| 85 |
|
| 86 | vulcanize --strip-comments target.html
|
| 87 |
|
| 88 | will remove HTML comments, except for those that begin with `@license`.
|
| 89 | License comments will be deduplicated.
|
| 90 |
|
| 91 | ## Using vulcanize programmatically
|
| 92 |
|
| 93 | Vulcanize as a library has two exported function.
|
| 94 |
|
| 95 | `vulcanize` constructor takes an object of options similar to the command line
|
| 96 | options.
|
| 97 | - `abspath`: A folder to treat as "webroot".
|
| 98 | - When specified, use an absolute path to `target`.
|
| 99 | - `excludes`: An array of strings with regular expressions to exclude paths from being inlined.
|
| 100 | - `stripExcludes`: Similar to `excludes`, but strips the imports from the output entirely.
|
| 101 | - If `stripExcludes` is empty, it will be set the value of `excludes` by default.
|
| 102 | - `inlineScripts`: Inline external scripts.
|
| 103 | - `inlineCss`: Inline external stylesheets.
|
| 104 | - `addedImports`: Additional HTML imports to inline, added to the end of the
|
| 105 | target file
|
| 106 | - `redirects`: An array of strings with the format `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.
|
| 107 | - `stripComments`: Remove non-license HTML comments.
|
| 108 | - `inputUrl`: A URL string that will override the `target` argument to
|
| 109 | `vulcanize.process()`.
|
| 110 | By design, gulp and grunt plugins expect to work on the given file path.
|
| 111 | `vulcanize` has its own file loader, and expects to be given URLs. In
|
| 112 | instances where the filename cannot be used as a URL `inputUrl` will
|
| 113 | override the filename.
|
| 114 | - `loader`: A [hydrolysis](https://www.npmjs.com/package/hydrolysis) loader.
|
| 115 | This loader is generated with the `target` argument to `vulcan.process` and
|
| 116 | the `exclude` paths. A custom loader can be given if more advanced setups
|
| 117 | are necesssary.
|
| 118 |
|
| 119 | `vulcanize.process` takes a `target` path to `target.html` and a callback.
|
| 120 |
|
| 121 | Example:
|
| 122 | ```js
|
| 123 | var Vulcanize = require('vulcanize');
|
| 124 | var hydrolysis = require('hydrolysis');
|
| 125 |
|
| 126 | /* a Hydrolysis loader object (optional) */
|
| 127 | var loader = new hydrolysis.loader(...)
|
| 128 |
|
| 129 | var vulcan = new Vulcanize({
|
| 130 | abspath: '',
|
| 131 | excludes: [
|
| 132 | '\\.css$'
|
| 133 | ],
|
| 134 | stripExcludes: [
|
| 135 | ],
|
| 136 | inlineScripts: false,
|
| 137 | inlineCss: false,
|
| 138 | addedImports: [
|
| 139 | ],
|
| 140 | redirects: [
|
| 141 | ],
|
| 142 | implicitStrip: true,
|
| 143 | stripComments: false
|
| 144 | // optional
|
| 145 | loader: loader,
|
| 146 | inputUrl: ''
|
| 147 | });
|
| 148 |
|
| 149 | vulcan.process(target, function(err, inlinedHtml) {
|
| 150 | });
|
| 151 | ```
|
| 152 |
|
| 153 | ## Caveats
|
| 154 |
|
| 155 | Because HTML Imports changes the order of execution scripts can have, Vulcanize
|
| 156 | has to make a few compromises to achieve that same script execution order.
|
| 157 |
|
| 158 | 1. Contents of all HTML Import documents will be moved to `<body>`
|
| 159 |
|
| 160 | 1. 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.
|
| 161 |
|
| 162 | ## What happened to [feature] from 0.X?
|
| 163 | - `--csp` mode has been moved into [crisper](https://github.com/PolymerLabs/crisper)
|
| 164 | - `--strip` mode was removed, use something like [html-minifier](https://github.com/kangax/html-minifier) or [minimize](https://github.com/Moveo/minimize)
|
| 165 | - 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)
|
| 166 |
|
| 167 | ## What about build tools
|
| 168 | - [grunt-vulcanize](https://www.npmjs.com/package/grunt-vulcanize)
|
| 169 | - [gulp-vulcanize](https://www.npmjs.com/package/gulp-vulcanize)
|
| 170 | - [broccoli-vulcanize](https://www.npmjs.com/package/broccoli-vulcanize)
|
| 171 |
|
| 172 | [](https://github.com/igrigorik/ga-beacon)
|