# polymer-bundler

> Process Web Components into one output file

Latest version **4.0.10** (published 2019-06-04) · BSD-3-Clause license · 0 weekly downloads

## Install

```sh
npm install polymer-bundler
pnpm add polymer-bundler
yarn add polymer-bundler
bun add polymer-bundler
```

Provides the command `polymer-bundler`.

## Health

**Score 35/100 (D)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 4.0.10 |
| Published | 2019-06-04 |
| First published | 2016-10-17 |
| Weekly downloads | 0 |
| License | BSD-3-Clause |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 17 |
| Unpacked size | 338.8 KB |
| Known vulnerabilities | 0 (+3 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 437 |
| Author | The Polymer Project Authors |
| Maintainers | aomarks, azakus, bicknellr, emarquez, justinfagnani, keanulee, notwaldorf, polymer-devs, samli, sorvell, tvanderlippe, usergenic |
| Keywords | web components, polymer |

## Links

- npm: https://www.npmjs.com/package/polymer-bundler
- Repository: https://github.com/Polymer/tools
- Homepage: https://github.com/Polymer/tools/tree/master/packages/bundler
- Issues: https://github.com/Polymer/tools/issues
- npm.io page: https://npm.io/package/polymer-bundler

## Dependencies (17)

- [dom5](https://npm.io/package/dom5.md) ^3.0.0
- [clone](https://npm.io/package/clone.md) ^2.1.0
- [espree](https://npm.io/package/espree.md) ^3.5.2
- [mkdirp](https://npm.io/package/mkdirp.md) ^0.5.1
- [parse5](https://npm.io/package/parse5.md) ^4.0.0
- [rollup](https://npm.io/package/rollup.md) ^1.3.0
- [source-map](https://npm.io/package/source-map.md) ^0.5.6
- [vscode-uri](https://npm.io/package/vscode-uri.md) =1.0.6
- [babel-types](https://npm.io/package/babel-types.md) ^6.26.0
- [magic-string](https://npm.io/package/magic-string.md) ^0.22.4
- [babel-traverse](https://npm.io/package/babel-traverse.md) ^6.26.0
- [babel-generator](https://npm.io/package/babel-generator.md) ^6.26.1
- [polymer-analyzer](https://npm.io/package/polymer-analyzer.md) ^3.2.2
- [command-line-args](https://npm.io/package/command-line-args.md) ^5.0.2
- [command-line-usage](https://npm.io/package/command-line-usage.md) ^5.0.5
- [@types/babel-traverse](https://npm.io/package/@types/babel-traverse.md) ^6.25.3
- [@types/babel-generator](https://npm.io/package/@types/babel-generator.md) ^6.25.1

## Recent versions

- 4.0.10 (latest) — 2019-06-04
- 4.0.0-pre.7 (next) — 2018-05-04
- 2.0.0-pre.18 (alpha) — 2017-05-15
- 4.0.9 — 2019-03-02
- 4.0.8 — 2019-02-13
- 4.0.7 — 2019-02-01
- 4.0.6 — 2019-01-19
- 4.0.5 — 2019-01-10
- 4.0.4 — 2018-10-18
- 4.0.3 — 2018-10-16
- 4.0.2 — 2018-06-28
- 4.0.1 — 2018-05-14
- 4.0.0 — 2018-05-08
- 4.0.0-pre.6 — 2018-04-26
- 4.0.0-pre.5 — 2018-04-17
- … 38 more at https://npm.io/package/polymer-bundler/versions

## README

[![Build Status](https://travis-ci.org/Polymer/polymer-bundler.svg?branch=master)](https://travis-ci.org/Polymer/polymer-bundler)
[![NPM version](http://img.shields.io/npm/v/polymer-bundler.svg)](https://www.npmjs.com/package/polymer-bundler)

# 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](https://github.com/Polymer/polymer-cli) uses [polymer-build](https://github.com/Polymer/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](http://www.html5rocks.com/en/tutorials/webcomponents/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](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 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 <path> instead of stdout.
- `--out-dir <path>`: If specified, output will be written to <path>. 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 scripts
- `inlineCss`: 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](https://github.com/Polymer/tools/blob/master/packages/bundler/src/bundle-manifest.ts).
- `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](https://github.com/Polymer/tools/blob/master/packages/bundler/src/bundle-manifest.ts)

`.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:
```js
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:
```js
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,
  // Merge shared dependencies into a single bundle when
  // they have at least three dependents.
  strategy: generateSharedDepsMergeStrategy(3),
  // Shared bundles will be named:
  // `shared/bundle_1.html`, `shared/bundle_2.html`, etc...
  urlMapper: generateCountingSharedBundleUrlMapper('shared/bundle_')
});

// Provide the strategy and the URL mapper to produce a
// manifest using custom behavior.
bundler.generateManifest(['item.html', 'cart.html']).then((manifest) => {
  bundler.bundle(manifest).then((result) => {
    // do stuff here with your BundleResult
  });
});
```

## 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:

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

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.

---
_Source: https://npm.io/package/polymer-bundler · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._