Bundler for Progressive Web Component libraries built with Elena

Table of contents

• Install
• CLI usage
• Configuration
  • Options
• Build output
• Programmatic API

Install

npm install --save-dev @elenajs/bundler

CLI usage

The bundler provides an elena CLI binary with build and watch commands:

npx elena build

If no command is provided, build is assumed:

npx elena

To start a watch session that rebuilds on file changes:

npx elena watch

Flags

| Flag | Description | | ------------------ | ------------------------------------------------------------------------------------------- | | --config <path> | Path to a config file. Defaults to elena.config.mjs or elena.config.js in the project root. |

Example:

npx elena build --config config/elena.config.mjs

Configuration

Create an elena.config.mjs (or elena.config.js) at the root of your package:

/**
 * ░ [ELENA]: Bundler configuration
 *
 * @type {import("@elenajs/bundler").ElenaConfig}
 */
export default {
  // Source directory scanned for .js/.ts entry files and .css files.
  input: "src",

  // Rollup output options.
  output: {
    dir: "dist",
    format: "esm",
    sourcemap: true,
  },

  // Entry for the single-file bundle. Set to false to disable.
  bundle: "src/index.js",

  // Additional Rollup plugins appended after Elena's built-in set.
  // plugins: [],

  // Custom Elements Manifest options. Set to false to skip entirely.
  // analyze: {
  //   plugins: [],
  // },

  // Browserslist targets for transpilation. Enables syntax transforms
  // (e.g. class fields, optional chaining) to widen browser support.
  // target: ["chrome 71", "firefox 69", "safari 12.1"],

  // Custom Terser minifier options, merged with the defaults.
  // terser: { ecma: 2020, module: true },

  // Banner comment prepended to bundle output files.
  // Use a @license tag so minifiers preserve it.
  // banner: `/** @license MIT */`,
};

Options

| Option | Type | Default | Description | | ------------------ | ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | | input | string | "src" | Source directory to scan for .js, .ts, and .css files. | | output.dir | string | "dist" | Output directory for compiled files. | | output.format | string | "esm" | Rollup output format. | | output.sourcemap | boolean | true | Whether to emit sourcemaps. | | bundle | string \| false | "src/index.js" | Entry point for the single-file bundle. Auto-detects src/index.ts if no .js entry exists. Set to false to disable. | | plugins | Plugin[] | [] | Additional Rollup plugins appended after the built-in set. | | analyze | object \| false | { plugins: [] } | CEM analysis options. Set to false to skip Custom Elements Manifest generation, TypeScript declarations, and JSX types entirely. | | analyze.plugins | Plugin[] | [] | Additional CEM analyzer plugins. | | target | string \| string[] \| false | false | Browserslist target(s) for transpilation. When set, enables syntax transforms (e.g. class fields, optional chaining) via @babel/preset-env to widen browser support. Example: ["chrome 71", "firefox 69", "safari 12.1"]. | | terser | object | { ecma: 2020, module: true } | Custom Terser minifier options, merged with the defaults. See the Terser API docs for available options. | | banner | string \| false | false | Banner comment prepended to index.js and bundle.js output files. Use a @license JSDoc tag so minifiers preserve it. |

Build output

Running elena build produces:

| File | Description | | --------------------------- | ---------------------------------------------------------------------------------------------------- | | dist/*.js | Individual ES modules for each source file. | | dist/*.css | Minified individual CSS files. | | dist/bundle.js | Single-file JavaScript bundle (optional). | | dist/bundle.css | Concatenated and minified CSS bundle. CSS files imported as CSS Module Scripts (with { type: "css" }) for Shadow DOM are excluded. | | dist/custom-elements.json | Custom Elements Manifest describing all components. | | dist/custom-elements.d.ts | JSX integration types mapping tag names to prop types. | | dist/*.d.ts | Per-component TypeScript declarations with typed props and events. |

Note: CSS files that are imported as CSS Module Scripts for Shadow DOM use (import styles from "./button.css" with { type: "css" }) are inlined as CSSStyleSheet objects in the JavaScript output and excluded from bundle.css. Individual .css files are still emitted.

TypeScript support

The bundler supports both JavaScript and TypeScript source files. When .ts files are detected in the source directory, the bundler automatically transpiles them to JavaScript using @rollup/plugin-typescript. The output is identical to what you get from JavaScript sources.

To use TypeScript, write your components with inline type annotations instead of JSDoc:

import { Elena, html } from "@elenajs/core";

export default class Button extends Elena(HTMLElement) {
  static tagName = "elena-button";
  static props = ["variant"];

  /**
   * The style variant of the component.
   * @property
   */
  variant: "default" | "primary" | "danger" = "default";

  render() {
    return html`<button>${this.text}</button>`;
  }
}
Button.define();

A tsconfig.json is required in the project root. A minimal configuration:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "skipLibCheck": true
  },
  "include": ["src"]
}

Note: The bundler handles TypeScript declarations separately via the CEM analyzer, you do not need declaration: true in your tsconfig.json.

Programmatic API

The bundler exports its internals so you can integrate it into your own build scripts:

import {
  createRollupConfig,
  runRollupBuild,
  watchRollupBuild,
  createCemConfig,
  runCemAnalyze,
} from "@elenajs/bundler";

Sub-path imports are also available:

import { createRollupConfig, runRollupBuild, watchRollupBuild } from "@elenajs/bundler/rollup";
import { createCemConfig, runCemAnalyze } from "@elenajs/bundler/cem";

createRollupConfig(options?)

Returns a Rollup configuration array. Useful if you want to wrap or extend the config in a custom rollup.config.js.

runRollupBuild(config)

Runs both build phases (individual modules + optional single-file bundle) programmatically.

watchRollupBuild(config, opts?)

Starts a Rollup watch session that rebuilds on file changes. Returns the Rollup watcher instance. Pass opts.onRebuild as an async callback to run after each successful rebuild (e.g. to re-run CEM analysis).

createCemConfig(options?)

Returns the Custom Elements Manifest analyzer configuration object.

runCemAnalyze(config, cwd?)

Runs the CEM analysis and writes custom-elements.json, custom-elements.d.ts, and per-component .d.ts files.

License

MIT

Copyright

Copyright © 2026 Ariel Salminen