Registry / web-framework / polymer-build

polymer-build

JSON →
library3.1.4jsnpmunverified

Polymer Build (current version 3.1.4) is a Node.js library designed for building Polymer web component projects. It provides a highly customizable, stream-based pipeline for processing project source files and their dependencies, using Vinyl file objects. While the Polymer CLI utilizes `polymer-build` internally for its `build` command, this library offers greater flexibility for developers who require custom build steps, specific optimizers, or advanced stream manipulations not available through the CLI's pre-configured options. `polymer-build` enables direct interaction with build streams, allowing integration with other Node.js stream-based tools like Gulp. The Polymer ecosystem, including `polymer-build`, has largely been superseded by Lit for modern web component development, meaning this library is in a deprecated state with no new feature development expected.

npm install polymer-build
INSTALL
IMPORT
SIG · POLYMER-BUILD
P
polymer-build
web-frameworkjavascriptv3.1.4
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

PolymerProject
import { PolymerProject } from 'polymer-build';
const PolymerProject = require('polymer-build').PolymerProject;
The primary class for configuring and managing a Polymer build pipeline. While `require()` is shown in older examples, modern TypeScript/ESM projects should use named imports. Direct `require('polymer-build')` returns the module, not the class directly.
HtmlSplitter
import { HtmlSplitter } from 'polymer-build';
const HtmlSplitter = require('polymer-build').HtmlSplitter;
Used to extract inlined CSS and JavaScript from HTML files into separate stream files for easier processing by other tools. Follows the same import pattern as `PolymerProject`.
ProjectOptions
import type { ProjectOptions } from 'polymer-build';
This is a type-only import for the configuration object used by the `PolymerProject` constructor. Essential for TypeScript users to ensure correct project configuration.

This quickstart demonstrates how to initialize a `PolymerProject` instance using either a `polymer.json` file or a default configuration. It then combines the project's source and dependency streams using `merge-stream` for a basic Gulp-based build process, outputting files to a `build/default` directory. It highlights the stream-centric nature of `polymer-build` and its integration with Gulp.

import { PolymerProject } from 'polymer-build'; import gulp from 'gulp'; import mergeStream from 'merge-stream'; import { resolve } from 'path'; import { readFileSync, existsSync } from 'fs'; // This example demonstrates a basic Polymer build pipeline using Gulp. // Ensure 'gulp', 'merge-stream', and 'polymer-build' are installed. // For a real project, replace 'dummy-app' with your project structure. const polymerJsonPath = resolve(process.cwd(), 'polymer.json'); let projectConfig = {}; if (existsSync(polymerJsonPath)) { projectConfig = JSON.parse(readFileSync(polymerJsonPath, 'utf-8')); } else { // Fallback to a minimal example config if polymer.json is not found console.warn('polymer.json not found. Using a default example configuration.'); projectConfig = { entrypoint: 'index.html', shell: 'src/my-app.html', // Adjust based on your app shell fragments: ['src/my-view1.html', 'src/my-view2.html'], // Example fragments sources: ['src/**/*', 'index.html', '!node_modules/**/*'], // Include all sources, exclude node_modules extraDependencies: ['node_modules/@webcomponents/webcomponentsjs/**/*'], // Example polyfills }; } // Create a PolymerProject instance with the determined configuration const project = new PolymerProject(projectConfig); gulp.task('build', () => { console.log('Starting Polymer build...'); // Merge project sources and dependencies into a single stream const mergedStreams = mergeStream(project.sources(), project.dependencies()); return mergedStreams // You can add custom build steps here, e.g., linting, optimization, minification // .pipe(myCustomOptimizer()) .pipe(gulp.dest('build/default')) // Output to a 'build/default' directory .on('end', () => console.log('Polymer build completed. Output in build/default/.')); }); // To run this Gulp task: // 1. Install dependencies: `npm install --save-dev gulp merge-stream polymer-build` // 2. Create a `gulpfile.ts` (or `.js`) in your project root with this code. // 3. Create a basic `index.html` and `src/my-app.html` (or other configured entrypoints). // 4. Run `npx gulp build` from your terminal.
polymer --version
Debug
Known issues
deprecatedThe Polymer project ecosystem, including `polymer-build`, is deprecated and has been succeeded by Lit for modern web component development. No new features are expected, and maintenance is minimal.
fix
Consider migrating new projects or existing Polymer 3 projects to Lit for future development. `polymer-build` remains usable for existing Polymer 2.x/3.x applications but will not receive active feature development or significant updates.
affects: >=3.0.0
gotchaPolymer CLI uses `polymer-build` internally. Using `polymer-build` directly provides greater customization but means you are responsible for integrating all build steps (e.g., optimization, bundling, service worker generation) that the CLI might handle automatically.
fix
Determine if the Polymer CLI's built-in `build` command meets your needs. If not, understand that `polymer-build` offers a lower-level API requiring more manual pipeline construction and integration with other Gulp/Node.js stream tools.
affects: >=3.0.0
gotcha`PolymerProject` configuration can be loaded from `polymer.json` or passed directly as an object. Mismatching paths or missing `entrypoint`, `shell`, or `fragments` can lead to incomplete builds or errors.
fix
Ensure `polymer.json` is correctly structured and accessible, or that the `PolymerProject` constructor receives accurate `entrypoint`, `shell`, `fragments`, `sources`, and `extraDependencies` paths. Use glob patterns carefully for `sources` and `extraDependencies`.
affects: >=3.0.0
Errors
Common errors & fixes
TypeError: project.sources is not a function
The `PolymerProject` class was not correctly instantiated, or the variable `project` refers to the module itself rather than an instance of `PolymerProject`.
fix
Ensure you create an instance of `PolymerProject` using `const project = new PolymerProject(config);` before attempting to call its methods like `project.sources()`.
ENOENT: no such file or directory, open 'polymer.json'
The `polymer.json` configuration file, which is often loaded via `require('./polymer.json')` or `readFileSync`, does not exist at the specified path.
fix
Verify the path to your `polymer.json` file. If you don't have one, pass the configuration object directly to the `PolymerProject` constructor instead of attempting to load from `polymer.json`.
Error: No matching shell found.
The `shell` path configured in `PolymerProject` (or `polymer.json`) does not point to a valid HTML file intended as the application shell, or the file is not reachable within the project's source/dependency graph.
fix
Check the `shell` property in your `PolymerProject` configuration. Ensure it correctly points to the main application shell HTML file and that the file exists and is accessible relative to your project root or defined `sources`.
Upgrade
Version history
3.1.4latest on npm
Audit
Dependencies
gulpoptionalCommonly used for defining build tasks that consume polymer-build streams and for destination piping.
merge-streamoptionalOften used to combine the project's source and dependency streams into a single pipeline.
Agent activity
2 hits · last 30 days
node
2
Resources
polymer-build — npm install polymer-build · libregistry