npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

vulcanize

v1.16.0

Published

Process Web Components into one output file

Downloads

15,391

Readme

NPM version Build Status

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.
  • excludes: An array of strings with regular expressions to exclude paths from being inlined.
  • stripExcludes: Similar to excludes, but strips the imports from the output entirely.
    • If stripExcludes is empty, it will be set the value of excludes by default.
  • inlineScripts: Inline external scripts.
  • inlineCss: Inline external stylesheets.
  • addedImports: Additional HTML imports to inline, added to the end of the target file
  • 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.
  • stripComments: Remove non-license HTML comments.
  • inputUrl: A URL string that will override the target argument to vulcanize.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 URL inputUrl will override the filename.
  • loader: A hydrolysis loader. This loader is generated with the target argument to vulcan.process and the exclude 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.

  1. Contents of all HTML Import documents will be moved to <body>

  2. 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)

What about build tools

Analytics