{"id":15762,"library":"polymer-build","title":"Polymer Build","description":"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.","status":"deprecated","version":"3.1.4","language":"javascript","source_language":"en","source_url":"https://github.com/Polymer/tools","tags":["javascript","typescript"],"install":[{"cmd":"npm install polymer-build","lang":"bash","label":"npm"},{"cmd":"yarn add polymer-build","lang":"bash","label":"yarn"},{"cmd":"pnpm add polymer-build","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Commonly used for defining build tasks that consume polymer-build streams and for destination piping.","package":"gulp","optional":true},{"reason":"Often used to combine the project's source and dependency streams into a single pipeline.","package":"merge-stream","optional":true}],"imports":[{"note":"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.","wrong":"const PolymerProject = require('polymer-build').PolymerProject;","symbol":"PolymerProject","correct":"import { PolymerProject } from 'polymer-build';"},{"note":"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`.","wrong":"const HtmlSplitter = require('polymer-build').HtmlSplitter;","symbol":"HtmlSplitter","correct":"import { HtmlSplitter } from 'polymer-build';"},{"note":"This is a type-only import for the configuration object used by the `PolymerProject` constructor. Essential for TypeScript users to ensure correct project configuration.","symbol":"ProjectOptions","correct":"import type { ProjectOptions } from 'polymer-build';"}],"quickstart":{"code":"import { PolymerProject } from 'polymer-build';\nimport gulp from 'gulp';\nimport mergeStream from 'merge-stream';\nimport { resolve } from 'path';\nimport { readFileSync, existsSync } from 'fs';\n\n// This example demonstrates a basic Polymer build pipeline using Gulp.\n// Ensure 'gulp', 'merge-stream', and 'polymer-build' are installed.\n// For a real project, replace 'dummy-app' with your project structure.\n\nconst polymerJsonPath = resolve(process.cwd(), 'polymer.json');\nlet projectConfig = {};\n\nif (existsSync(polymerJsonPath)) {\n  projectConfig = JSON.parse(readFileSync(polymerJsonPath, 'utf-8'));\n} else {\n  // Fallback to a minimal example config if polymer.json is not found\n  console.warn('polymer.json not found. Using a default example configuration.');\n  projectConfig = {\n    entrypoint: 'index.html',\n    shell: 'src/my-app.html', // Adjust based on your app shell\n    fragments: ['src/my-view1.html', 'src/my-view2.html'], // Example fragments\n    sources: ['src/**/*', 'index.html', '!node_modules/**/*'], // Include all sources, exclude node_modules\n    extraDependencies: ['node_modules/@webcomponents/webcomponentsjs/**/*'], // Example polyfills\n  };\n}\n\n// Create a PolymerProject instance with the determined configuration\nconst project = new PolymerProject(projectConfig);\n\ngulp.task('build', () => {\n  console.log('Starting Polymer build...');\n  // Merge project sources and dependencies into a single stream\n  const mergedStreams = mergeStream(project.sources(), project.dependencies());\n\n  return mergedStreams\n    // You can add custom build steps here, e.g., linting, optimization, minification\n    // .pipe(myCustomOptimizer())\n    .pipe(gulp.dest('build/default')) // Output to a 'build/default' directory\n    .on('end', () => console.log('Polymer build completed. Output in build/default/.'));\n});\n\n// To run this Gulp task:\n// 1. Install dependencies: `npm install --save-dev gulp merge-stream polymer-build`\n// 2. Create a `gulpfile.ts` (or `.js`) in your project root with this code.\n// 3. Create a basic `index.html` and `src/my-app.html` (or other configured entrypoints).\n// 4. Run `npx gulp build` from your terminal.","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"deprecated","affected_versions":">=3.0.0"},{"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.","message":"Polymer 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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`.","message":"`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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you create an instance of `PolymerProject` using `const project = new PolymerProject(config);` before attempting to call its methods like `project.sources()`.","cause":"The `PolymerProject` class was not correctly instantiated, or the variable `project` refers to the module itself rather than an instance of `PolymerProject`.","error":"TypeError: project.sources is not a function"},{"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`.","cause":"The `polymer.json` configuration file, which is often loaded via `require('./polymer.json')` or `readFileSync`, does not exist at the specified path.","error":"ENOENT: no such file or directory, open 'polymer.json'"},{"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`.","cause":"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.","error":"Error: No matching shell found."}],"ecosystem":"npm"}