{"id":17875,"library":"polymer-bundler","title":"Polymer Bundler","description":"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.","status":"abandoned","version":"4.0.10","language":"javascript","source_language":"en","source_url":"https://github.com/Polymer/tools","tags":["javascript","web components","polymer","typescript"],"install":[{"cmd":"npm install polymer-bundler","lang":"bash","label":"npm"},{"cmd":"yarn add polymer-bundler","lang":"bash","label":"yarn"},{"cmd":"pnpm add polymer-bundler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally by the Bundler constructor to provide analysis of and access to files for bundling.","package":"polymer-analyzer","optional":false}],"imports":[{"note":"The primary class for programmatic bundling. Instantiated with an options object.","wrong":"const Bundler = require('polymer-bundler').Bundler;","symbol":"Bundler","correct":"import { Bundler } from 'polymer-bundler';"},{"note":"Used to produce a manifest, which the `Bundler.bundle()` method now accepts directly.","wrong":"const generateManifest = require('polymer-bundler').generateManifest;","symbol":"generateManifest","correct":"import { generateManifest } from 'polymer-bundler';"},{"note":"TypeScript type for the output of the bundling process.","symbol":"BundleResult","correct":"import type { BundleResult } from 'polymer-bundler';"}],"quickstart":{"code":"npm install -g polymer-bundler\n\n# Create a simple HTML file to bundle\necho '\\n\\n\\n Test App\\n \\n \\n \\n\\n\\n \\n\\n' > index.html\n\necho '\\n \\n \\n' > my-component.html\n\necho 'console.log(\"App loaded!\");' > app.js\n\n# Bundle the application, inlining scripts and styles, and stripping comments\npolymer-bundler index.html \\\n --inline-scripts \\\n --inline-css \\\n --strip-comments \\\n --out-file bundled-app.html\n\n# To view the output:\n# cat bundled-app.html","lang":"bash","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.2.0"},{"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.","message":"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()`.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"URL rewriting behavior for elements within `