Polymer Bundler
raw JSON → 4.0.10 verified Thu Apr 23 auth: no javascript abandoned
polymer-bundler is a JavaScript library and command-line tool (CLI) designed for optimizing web component-based projects by processing and packaging project assets into a single output file. Its primary function, integral to the Polymer 1.x and 2.x ecosystems, was to follow HTML Imports, external scripts, and stylesheets, inlining these resources into "bundles" to minimize network round-trips and improve initial load times in production environments. The package is at version 4.0.10. While it offers a programmatic API for custom bundling strategies, it was most commonly used via the Polymer CLI. However, its core utility is significantly diminished as HTML Imports, the foundational web standard it built upon, were deprecated in Chrome M70 and removed entirely in Chrome M80 (February 2020) due to lack of adoption across browsers and the rise of ES Modules. Therefore, while the package exists, its practical application for modern web development is largely obsolete.
Common errors
error Command not found: polymer-bundler ↓
cause The `polymer-bundler` CLI tool is not installed globally or is not in your system's PATH.
fix
Install the package globally using
npm install -g polymer-bundler (or sudo npm install -g polymer-bundler on some systems). error ENOENT: no such file or directory, stat 'index.html' ↓
cause The specified input HTML file (e.g., `index.html`) does not exist at the provided path, or the command is being run from the wrong directory.
fix
Ensure the input HTML file exists and the path is correct, or navigate to the directory containing the file before running the command.
error HTML Import parsing error: unexpected token < ↓
cause Often occurs when an HTML Import tries to load a non-HTML file (like a script or JSON) or a malformed HTML file.
fix
Verify that all
<link rel="import"> tags point to valid HTML documents and that those documents are well-formed. Warnings
breaking The core utility of polymer-bundler, which relies on HTML Imports for asset bundling, is fundamentally broken for modern browsers. HTML Imports were deprecated in Chrome M70 and removed in M80 (February 2020) and were never widely adopted by other browsers. Projects heavily dependent on HTML Imports will no longer function natively in modern browsers without polyfills, severely limiting the practical use of this bundler. ↓
fix For new projects, use modern web component tooling with ES Modules (e.g., Lit, Vite, Webpack, Rollup). For legacy projects, consider migrating away from HTML Imports or ensuring robust polyfill strategies are in place, understanding the inherent limitations.
gotcha External scripts and stylesheets are not inlined into the bundle by default. If these resources are not explicitly inlined, they will remain as external links in the bundled output, potentially negating performance benefits. ↓
fix Always include the `--inline-scripts` and `--inline-css` flags when using the CLI if you intend for external resources to be inlined into the main bundle.
breaking Between major versions and even minor updates (e.g., in 2.x), the programmatic API for `polymer-bundler` underwent significant changes. For instance, the `bundle()` method in 2.0.0+ now expects a manifest object instead of separate entrypoints, strategy, and mapper arguments, requiring the use of `generateManifest()`. ↓
fix Refer to the specific version's API documentation, particularly the `CHANGELOG.md` or `README`, for correct programmatic usage, especially regarding the `bundle()` method and manifest generation.
gotcha URL rewriting behavior for elements within `<template>` tags differs between Polymer 1.x and 2.x. Polymer 1.x projects using relative image URLs in styles within `<template>` tags might render incorrectly after bundling if `--rewrite-urls-in-templates` is not used. Polymer 2.x handles this differently with `assetpath`. ↓
fix For Polymer 1.x projects experiencing broken relative URLs in templated styles, explicitly use the `--rewrite-urls-in-templates` flag. For Polymer 2.x, ensure `assetpath` is correctly utilized.
deprecated The Polymer library itself is in maintenance mode, with LitElement recommended for new development. As a foundational tool for older Polymer versions, `polymer-bundler` is consequently also a legacy tool. ↓
fix Consider migrating projects to LitElement and modern build tools (e.g., Vite, Webpack, Rollup) for active development and long-term maintainability.
Install
npm install polymer-bundler yarn add polymer-bundler pnpm add polymer-bundler Imports
- Bundler wrong
const Bundler = require('polymer-bundler').Bundler;correctimport { Bundler } from 'polymer-bundler'; - generateManifest wrong
const generateManifest = require('polymer-bundler').generateManifest;correctimport { generateManifest } from 'polymer-bundler'; - BundleResult
import type { BundleResult } from 'polymer-bundler';
Quickstart
npm install -g polymer-bundler
# Create a simple HTML file to bundle
echo '<!DOCTYPE html>\n<html>\n<head>\n <title>Test App</title>\n <link rel="import" href="./my-component.html">\n <style>body { font-family: sans-serif; }</style>\n <script src="./app.js"></script>\n</head>\n<body>\n <my-component></my-component>\n</body>\n</html>' > index.html
echo '<dom-module id="my-component">\n <template>\n <style>h1 { color: blue; }</style>\n <h1>Hello from My Component!</h1>\n </template>\n <script>class MyComponent extends HTMLElement { constructor() { super(); this.attachShadow({mode: "open"}).appendChild(document.getElementById("my-component").content.cloneNode(true)); } } customElements.define("my-component", MyComponent);</script>\n</dom-module>' > my-component.html
echo 'console.log("App loaded!");' > app.js
# Bundle the application, inlining scripts and styles, and stripping comments
polymer-bundler index.html \
--inline-scripts \
--inline-css \
--strip-comments \
--out-file bundled-app.html
# To view the output:
# cat bundled-app.html