@elenajs/bundler 0.6.0 → 0.8.0

package/README.md

@@ -0,0 +1,200 @@
+<div align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://elenajs.com/img/elena-dark.png" alt="Elena" width="201" height="230">
+  </source>
+  <source media="(prefers-color-scheme: light)" srcset="https://elenajs.com/img/elena.png" alt="Elena" width="201" height="230">
+  </source>
+  <img src="https://elenajs.com/img/elena.png" alt="Elena" width="201" height="230">
+</picture>
+
+### Bundler for Progressive Web Component libraries built with Elena.
+
+<br/>
+
+<a href="https://arielsalminen.com"><img src="https://img.shields.io/badge/creator-@arielle-F95B1F" alt="Creator @arielle"/></a>
+<a href="https://www.npmjs.com/package/@elenajs/bundler"><img src="https://img.shields.io/npm/v/@elenajs/bundler.svg" alt="Latest version on npm" /></a>
+<a href="https://github.com/getelena/elena/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="Elena is released under the MIT license." /></a>
+<a href="https://github.com/getelena/elena/actions/workflows/tests.yml"><img src="https://github.com/getelena/elena/actions/workflows/tests.yml/badge.svg" alt="Tests status" /></a>
+
+</div>
+
+<br/>
+
+<p align="center"><strong>@elenajs/bundler</strong> is the build tool for <a href="https://elenajs.com">Elena</a> Progressive Web Component libraries. It bundles JavaScript and TypeScript source files, minifies CSS, generates a <a href="https://custom-elements-manifest.open-wc.org/">Custom Elements Manifest</a>, and produces TypeScript declarations for Elena components.</p>
+
+<br/>
+
+## Table of contents
+
+- **[Install](#install)**
+- **[CLI usage](#cli-usage)**
+- **[Configuration](#configuration)**
+  - **[Options](#options)**
+- **[Build output](#build-output)**
+- **[Programmatic API](#programmatic-api)**
+
+## Install
+
+```bash
+npm install --save-dev @elenajs/bundler
+```
+
+## CLI usage
+
+The bundler provides an `elena` CLI binary with a single `build` command:
+
+```bash
+npx elena build
+```
+
+If no command is provided, `build` is assumed:
+
+```bash
+npx elena
+```
+
+## Configuration
+
+Create an `elena.config.mjs` (or `elena.config.js`) at the root of your package:
+
+```js
+/**
+ * ░ [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.
+  // analyze: {
+  //   plugins: [],
+  // },
+};
+```
+
+### 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.plugins`  | `Plugin[]`        | `[]`             | Additional CEM analyzer plugins.                                                                                         |
+
+## 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.                                                                |
+| `dist/custom-elements.json` | [Custom Elements Manifest](https://custom-elements-manifest.open-wc.org/) 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.                                   |
+
+## 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:
+
+```ts
+import { Elena, html } from "@elenajs/core";
+
+export default class Button extends Elena(HTMLElement, {
+  tagName: "elena-button",
+  props: ["variant"],
+}) {
+  /**
+   * The style variant of the component.
+   * @attribute
+   */
+  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:
+
+```json
+{
+  "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:
+
+```js
+import {
+  createRollupConfig,
+  runRollupBuild,
+  createCemConfig,
+  runCemAnalyze,
+} from "@elenajs/bundler";
+```
+
+Sub-path imports are also available:
+
+```js
+import { createRollupConfig, runRollupBuild } 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.
+
+### `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](https://arielsalminen.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elenajs/bundler",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Bundler for Progressive Web Component libraries built with Elena.",
   "author": "Elena <hi@elenajs.com>",
   "homepage": "https://elenajs.com/",
@@ -24,25 +24,27 @@
     "node": ">= 20"
   },
   "scripts": {
-    "format": "prettier --write \"src/**/*.js\" \"test/**/*.mjs\"",
     "test": "vitest run"
   },
   "dependencies": {
     "@custom-elements-manifest/analyzer": "0.11.0",
-    "@elenajs/plugin-cem-define": "^0.1.0",
-    "@elenajs/plugin-cem-tag": "^0.1.0",
-    "@elenajs/plugin-cem-typescript": "^0.2.0",
-    "@elenajs/plugin-rollup-css": "^0.3.0",
+    "@elenajs/plugin-cem-define": "^0.3.0",
+    "@elenajs/plugin-cem-tag": "^0.3.0",
+    "@elenajs/plugin-cem-typescript": "^0.4.0",
+    "@elenajs/plugin-rollup-css": "^0.5.0",
     "@rollup/plugin-node-resolve": "16.0.3",
     "@rollup/plugin-terser": "0.4.4",
+    "@rollup/plugin-typescript": "^12.1.0",
     "custom-element-jsx-integration": "1.6.0",
-    "globby": "11.0.4",
-    "rollup": "4.57.1",
+    "globby": "16.1.1",
+    "rollup": "4.58.0",
     "rollup-plugin-minify-html-literals-v3": "^1.3.4",
-    "rollup-plugin-summary": "3.0.1"
+    "rollup-plugin-summary": "3.0.1",
+    "tslib": "^2.8.0",
+    "typescript": "^5.8.0"
   },
   "devDependencies": {
     "vitest": "4.0.18"
   },
-  "gitHead": "3da2b4411c0a4d36085b1095feabbaabea50909f"
+  "gitHead": "c181af0625f691a95a5cb1ef9adb0d7f2c796eae"
 }

package/src/cem-analyze.js

@@ -1,18 +1,32 @@
+/**
+ *  ██████████ ████
+ * ░░███░░░░░█░░███
+ *  ░███  █ ░  ███   ██████  ████████    ██████
+ *  ░██████    ███  ███░░███░░███░░███  ░░░░░███
+ *  ░███░░█    ███ ░███████  ░███ ░███   ███████
+ *  ░███ ░   █ ███ ░███░░░   ░███ ░███  ███░░███
+ *  ██████████ █████░░██████  ████ █████░░████████
+ * ░░░░░░░░░░ ░░░░░  ░░░░░░  ░░░░ ░░░░░  ░░░░░░░░
+ *
+ * Elena Bundler CEM Analyze
+ * https://elenajs.com
+ */
+
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
 import { join, resolve } from "path";
 import { create, ts } from "@custom-elements-manifest/analyzer";
-import globby from "globby";
+import { globby } from "globby";
 import { customElementJsxPlugin as elenaJsxPlugin } from "custom-element-jsx-integration";
 import { elenaDefinePlugin } from "@elenajs/plugin-cem-define";
 import { elenaTagPlugin } from "@elenajs/plugin-cem-tag";
 import { elenaTypeScriptPlugin } from "@elenajs/plugin-cem-typescript";
-import { color } from "./utils/color.js";
+import { color } from "./common/color.js";
 
 /**
  * Returns the CEM config object for the given Elena config. Useful for advanced
  * users who still call the CEM CLI with a thin `elena.config.js` wrapper.
  *
- * @param {import("./utils/load-config.js").ElenaConfig} [options]
+ * @param {import("./common/load-config.js").ElenaConfig} [options]
  * @returns {object} CEM config object
  */
 export function createCemConfig(options = {}) {
@@ -24,8 +38,8 @@ export function createCemConfig(options = {}) {
     outdir,
     watch: false,
     dev: false,
-    globs: [`${src}/**/*.js`],
-    exclude: [`${src}/**/*.ts`, "**/*.test.js", "node_modules"],
+    globs: [`${src}/**/*.js`, `${src}/**/*.ts`],
+    exclude: ["**/*.test.js", "**/*.test.ts", "node_modules"],
     plugins: [
       elenaDefinePlugin(),
       elenaTagPlugin("status"),
@@ -41,7 +55,7 @@ export function createCemConfig(options = {}) {
  * Runs the CEM analyzer programmatically using `create()` from
  * `@custom-elements-manifest/analyzer`, writes the manifest to disk.
  *
- * @param {import("./utils/load-config.js").ElenaConfig} config
+ * @param {import("./common/load-config.js").ElenaConfig} config
  * @param {string} [cwd]
  * @returns {Promise<void>}
  */
@@ -57,14 +71,15 @@ export async function runCemAnalyze(config, cwd = process.cwd()) {
   console.log(` `);
 
   const globs = await globby(
-    [`${src}/**/*.js`, `!${src}/**/*.ts`, "!**/*.test.js", "!node_modules"],
+    [`${src}/**/*.js`, `${src}/**/*.ts`, "!**/*.test.js", "!**/*.test.ts", "!node_modules"],
     { cwd }
   );
 
   const modules = globs.map(glob => {
     const fullPath = resolve(cwd, glob);
     const source = readFileSync(fullPath).toString();
-    return ts.createSourceFile(glob, source, ts.ScriptTarget.ES2015, true);
+    const scriptKind = glob.endsWith(".ts") ? ts.ScriptKind.TS : ts.ScriptKind.JS;
+    return ts.createSourceFile(glob, source, ts.ScriptTarget.ES2015, true, scriptKind);
   });
 
   const plugins = [

package/src/cli.js

@@ -1,9 +1,23 @@
 #!/usr/bin/env node
 
-import { loadConfig } from "./utils/load-config.js";
+/**
+ *  ██████████ ████
+ * ░░███░░░░░█░░███
+ *  ░███  █ ░  ███   ██████  ████████    ██████
+ *  ░██████    ███  ███░░███░░███░░███  ░░░░░███
+ *  ░███░░█    ███ ░███████  ░███ ░███   ███████
+ *  ░███ ░   █ ███ ░███░░░   ░███ ░███  ███░░███
+ *  ██████████ █████░░██████  ████ █████░░████████
+ * ░░░░░░░░░░ ░░░░░  ░░░░░░  ░░░░ ░░░░░  ░░░░░░░░
+ *
+ * Elena Bundler CLI
+ * https://elenajs.com
+ */
+
+import { loadConfig } from "./common/load-config.js";
 import { runRollupBuild } from "./rollup-build.js";
 import { runCemAnalyze } from "./cem-analyze.js";
-import { color } from "./utils/color.js";
+import { color } from "./common/color.js";
 
 const BANNER = `
  ██████████ ████
@@ -18,6 +32,7 @@ const BANNER = `
 
 const [, , command = "build"] = process.argv;
 
+/** Loads the Elena config and runs the Rollup build + CEM analysis. */
 async function main() {
   if (command !== "build") {
     console.error(`Unknown command: ${command}. Usage: elena [build]`);

package/src/index.js

@@ -1,2 +1,16 @@
+/**
+ *  ██████████ ████
+ * ░░███░░░░░█░░███
+ *  ░███  █ ░  ███   ██████  ████████    ██████
+ *  ░██████    ███  ███░░███░░███░░███  ░░░░░███
+ *  ░███░░█    ███ ░███████  ░███ ░███   ███████
+ *  ░███ ░   █ ███ ░███░░░   ░███ ░███  ███░░███
+ *  ██████████ █████░░██████  ████ █████░░████████
+ * ░░░░░░░░░░ ░░░░░  ░░░░░░  ░░░░ ░░░░░  ░░░░░░░░
+ *
+ * Elena Bundler
+ * https://elenajs.com
+ */
+
 export { createRollupConfig, runRollupBuild } from "./rollup-build.js";
 export { createCemConfig, runCemAnalyze } from "./cem-analyze.js";

package/src/rollup-build.js

@@ -1,17 +1,38 @@
-import { readdirSync } from "fs";
+/**
+ *  ██████████ ████
+ * ░░███░░░░░█░░███
+ *  ░███  █ ░  ███   ██████  ████████    ██████
+ *  ░██████    ███  ███░░███░░███░░███  ░░░░░███
+ *  ░███░░█    ███ ░███████  ░███ ░███   ███████
+ *  ░███ ░   █ ███ ░███░░░   ░███ ░███  ███░░███
+ *  ██████████ █████░░██████  ████ █████░░████████
+ * ░░░░░░░░░░ ░░░░░  ░░░░░░  ░░░░ ░░░░░  ░░░░░░░░
+ *
+ * Elena Bundler Rollup Config
+ * https://elenajs.com
+ */
+
+import { existsSync, readdirSync } from "fs";
 import { rollup } from "rollup";
 import resolve from "@rollup/plugin-node-resolve";
 import terser from "@rollup/plugin-terser";
+import typescript from "@rollup/plugin-typescript";
 import minifyHtmlLiterals from "rollup-plugin-minify-html-literals-v3";
 import summary from "rollup-plugin-summary";
 import { cssPlugin, cssBundlePlugin } from "@elenajs/plugin-rollup-css";
-import { color } from "./utils/color.js";
+import { color } from "./common/color.js";
 
 const TREESHAKE = {
   moduleSideEffects: false,
   propertyReadSideEffects: false,
 };
 
+/**
+ * Suppresses noisy Rollup warnings.
+ *
+ * @param {import("rollup").RollupWarning} warning
+ * @param {function} warn
+ */
 function onwarn(warning, warn) {
   if (warning.code === "UNUSED_EXTERNAL_IMPORT") {
     return;
@@ -22,15 +43,36 @@ function onwarn(warning, warn) {
 /**
  * Builds the plugin list for a single Rollup build target.
  *
- * @param {{ src: string; outdir: string; hasSummary: boolean; includeCssBundle: boolean; extraPlugins?: import("rollup").Plugin[] }} opts
+ * @param {{ src: string; outdir: string; hasSummary: boolean; includeCssBundle: boolean; extraPlugins?: import("rollup").Plugin[]; hasTs?: boolean }} opts
  * @returns {import("rollup").Plugin[]}
  */
-function buildPlugins({ src, outdir, hasSummary, includeCssBundle, extraPlugins = [] }) {
-  const plugins = [
-    resolve({ extensions: [".js", ".css"] }),
+function buildPlugins({
+  src,
+  outdir,
+  hasSummary,
+  includeCssBundle,
+  extraPlugins = [],
+  hasTs = false,
+}) {
+  const plugins = [resolve({ extensions: [".js", ".ts", ".css"] })];
+
+  if (hasTs) {
+    plugins.push(
+      typescript({
+        sourceMap: true,
+        compilerOptions: {
+          declaration: false,
+          declarationMap: false,
+        },
+        include: ["**/*.ts"],
+      })
+    );
+  }
+
+  plugins.push(
     minifyHtmlLiterals({
       options: {
-        // Elena components use this.template`...` rather than html`...`
+        // Minify any template literal containing HTML, regardless of tag name
         shouldMinify: template => template.parts.some(({ text }) => /<[a-z]/i.test(text)),
       },
     }),
@@ -38,8 +80,8 @@ function buildPlugins({ src, outdir, hasSummary, includeCssBundle, extraPlugins
       ecma: 2020,
       module: true,
     }),
-    cssPlugin(src),
-  ];
+    cssPlugin(src)
+  );
 
   if (includeCssBundle) {
     plugins.push(cssBundlePlugin(src, "bundle.css"));
@@ -56,7 +98,7 @@ function buildPlugins({ src, outdir, hasSummary, includeCssBundle, extraPlugins
 }
 
 /**
- * Returns the Rollup config array for the given Elena config. Useful for advanced
+ * Returns the Rollup config array for the given Elena config. Useful for
  * users who want to call `rollup -c` with a thin wrapper config file.
  *
  * @param {import("./utils/load-config.js").ElenaConfig} [options]
@@ -67,13 +109,24 @@ export function createRollupConfig(options = {}) {
   const outdir = options.output?.dir ?? "dist";
   const format = options.output?.format ?? "esm";
   const sourcemap = options.output?.sourcemap ?? true;
-  const bundle = options.bundle !== undefined ? options.bundle : "src/index.js";
+  let bundle = options.bundle !== undefined ? options.bundle : "src/index.js";
   const extraPlugins = options.plugins ?? [];
 
   const entries = readdirSync(src, { recursive: true })
-    .filter(f => f.endsWith(".js"))
+    .filter(
+      f =>
+        (f.endsWith(".js") || f.endsWith(".ts")) &&
+        !f.endsWith(".test.js") &&
+        !f.endsWith(".test.ts")
+    )
     .map(f => `${src}/${f}`);
 
+  const hasTs = entries.some(f => f.endsWith(".ts"));
+
+  if (bundle === "src/index.js" && !existsSync(bundle) && existsSync("src/index.ts")) {
+    bundle = "src/index.ts";
+  }
+
   const configs = [
     {
       input: entries,
@@ -83,8 +136,14 @@ export function createRollupConfig(options = {}) {
         hasSummary: false,
         includeCssBundle: true,
         extraPlugins,
+        hasTs,
       }),
-      output: { format, sourcemap, dir: outdir },
+      output: {
+        format,
+        sourcemap,
+        dir: outdir,
+        ...(hasTs && { entryFileNames: "[name].js" }),
+      },
       preserveEntrySignatures: "strict",
       treeshake: TREESHAKE,
       onwarn,
@@ -100,6 +159,7 @@ export function createRollupConfig(options = {}) {
         hasSummary: true,
         includeCssBundle: false,
         extraPlugins,
+        hasTs,
       }),
       output: { format, sourcemap, file: `${outdir}/bundle.js` },
       preserveEntrySignatures: "strict",
@@ -112,62 +172,30 @@ export function createRollupConfig(options = {}) {
 }
 
 /**
- * Runs both Rollup build targets programmatically using the Rollup Node.js API.
- *
- * Note: the `output` key inside `RollupOptions` is ignored by the `rollup()` API.
- * Output options must be passed separately to `build.write()`.
+ * Runs Rollup build targets programmatically using the Rollup Node.js API.
+ * Reuses `createRollupConfig` to avoid duplicating config resolution logic.
  *
  * @param {import("./utils/load-config.js").ElenaConfig} config
  * @returns {Promise<void>}
  */
 export async function runRollupBuild(config) {
-  const src = config.input ?? "src";
-  const outdir = config.output?.dir ?? "dist";
-  const format = config.output?.format ?? "esm";
-  const sourcemap = config.output?.sourcemap ?? true;
-  const bundle = config.bundle !== undefined ? config.bundle : "src/index.js";
-  const extraPlugins = config.plugins ?? [];
+  const configs = createRollupConfig(config);
 
-  const entries = readdirSync(src, { recursive: true })
-    .filter(f => f.endsWith(".js"))
-    .map(f => `${src}/${f}`);
-
-  // Build 1: individual modules + CSS bundle
   console.log(color(`░█ [ELENA]: Building Progressive Web Components...`));
   console.log(` `);
-  for (const entry of entries) {
-    console.log(color(`░█ [ELENA]: Generating and minifying ${entry}...`));
-  }
-
-  const build1 = await rollup({
-    input: entries,
-    plugins: buildPlugins({ src, outdir, hasSummary: false, includeCssBundle: true, extraPlugins }),
-    preserveEntrySignatures: "strict",
-    treeshake: TREESHAKE,
-    onwarn,
-  });
-  await build1.write({ format, sourcemap, dir: outdir });
-  await build1.close();
-
-  // Build 2: single-file JS bundle (optional)
-  if (bundle) {
-    console.log(color(`░█ [ELENA]: Generating and minifying JS bundle...`));
-    console.log(` `);
 
-    const build2 = await rollup({
-      input: bundle,
-      plugins: buildPlugins({
-        src,
-        outdir,
-        hasSummary: true,
-        includeCssBundle: false,
-        extraPlugins,
-      }),
-      preserveEntrySignatures: "strict",
-      treeshake: TREESHAKE,
-      onwarn,
-    });
-    await build2.write({ format, sourcemap, file: `${outdir}/bundle.js` });
-    await build2.close();
+  for (const { output, ...inputOpts } of configs) {
+    if (Array.isArray(inputOpts.input)) {
+      for (const entry of inputOpts.input) {
+        console.log(color(`░█ [ELENA]: Generating and minifying ${entry}...`));
+      }
+    } else {
+      console.log(color(`░█ [ELENA]: Generating and minifying JS bundle...`));
+      console.log(` `);
+    }
+
+    const build = await rollup(inputOpts);
+    await build.write(output);
+    await build.close();
   }
 }