Polymer Build

Common errors

• TypeError: project.sources is not a function

  cause 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'

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

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

Warnings

• deprecated 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.
  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.
• gotcha 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.
  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.
• 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`.

Install

• npm install polymer-build npm
• yarn add polymer-build yarn
• pnpm add polymer-build pnpm

Imports

• PolymerProject
  wrong:

  const PolymerProject = require('polymer-build').PolymerProject;

  correct:

  import { PolymerProject } from 'polymer-build';

  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
  wrong:

  const HtmlSplitter = require('polymer-build').HtmlSplitter;

  correct:

  import { HtmlSplitter } from 'polymer-build';

  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.

Quickstart

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.