Registry / devops / polymer-bundler

polymer-bundler

library4.0.10jsnpmunverified

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.

devops

npm install polymer-bundler

github ↗package ↗

INSTALL

IMPORT

SIG · POLYMER-BUNDLER

polymer-bundler

devopsjavascriptv4.0.10

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Bundler

✓ import { Bundler } from 'polymer-bundler';

✗ const Bundler = require('polymer-bundler').Bundler;

The primary class for programmatic bundling. Instantiated with an options object.

generateManifest

✓ import { generateManifest } from 'polymer-bundler';

✗ const generateManifest = require('polymer-bundler').generateManifest;

Used to produce a manifest, which the `Bundler.bundle()` method now accepts directly.

BundleResult

✓ import type { BundleResult } from 'polymer-bundler';

TypeScript type for the output of the bundling process.

This quickstart demonstrates installing `polymer-bundler` globally and using it via the CLI to bundle a simple HTML application with a custom element and external resources. It inlines all scripts and styles, strips comments, and outputs to `bundled-app.html`.

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

Debug

Known issues

breakingThe 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.

affects: >=1.0.0

gotchaExternal 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.

affects: >=2.2.0

breakingBetween 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.

affects: >=2.0.0

gotchaURL 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.

affects: >=1.0.0

deprecatedThe 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.

affects: >=1.0.0

Errors

Common errors & fixes

Command not found: polymer-bundler

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

ENOENT: no such file or directory, stat 'index.html'

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.

HTML Import parsing error: unexpected token <

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.

Upgrade

Version history

4.0.10latest on npm

Audit

Dependencies

polymer-analyzerrequiredUsed internally by the Bundler constructor to provide analysis of and access to files for bundling.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/Polymer/tools ↗

packagehttps://www.npmjs.com/package/polymer-bundler ↗