Custom Elements Manifest Analyzer

A tool to statically analyze a project and generate a Custom Elements Manifest file, which is a JSON file that describes the custom elements defined in the project, their properties, methods, events, and other metadata.

This tool is largely inspired by—and in many parts directly based on—the @custom-elements-manifest/analyzer package by open-wc, with several significant architectural changes:

• This tool is designed to be used as a JavaScript module rather than a CLI, allowing for greater flexibility when integrating with other tools and build processes. It also minimizes external dependencies, making it lighter and faster to run.
• While the original package relies on TypeScript for file analysis, this tool can work with any Abstract Syntax Tree (AST) compatible with estree or its TypeScript variant. This allows users to choose the parser that best fits their project, such as oxc-parser, Rollup, or others.
• Since it does not perform full type checking, it can analyze the types of properties, methods, and events only when using Isolated Declarations.
• Mixin support is not currently planned.

Install

npm

npm i -D @chialab/cem-analyzer

yarn

yarn add -D @chialab/cem-analyzer

pnpm

pnpm add -D @chialab/cem-analyzer

Usage

Use the generate function to analyze source files and generate a Custom Elements Manifest:

import { readFile, writeFile } from 'node:fs/promises';
import { generate } from '@chialab/cem-analyzer';
import { parse } from 'oxc-parser';

const sourceFiles = await Promise.all([
    'src/components/my-element.ts',
    // other source files...
].map(async (file) => ({
    fileName: file,
    ...(await parse(await readFile(file, 'utf-8'))),
})));

const customElementsManifest = await generate(sourceFiles);

await writeFile(
    'custom-elements.json',
    JSON.stringify(customElementsManifest, null, 2)
);

Alternatively, you can use the bundle function to generate a bundled Custom Elements Manifest that includes all the source files in a single JSON file:

import { bundle } from '@chialab/cem-analyzer';

const sourceFiles = ...; // same as above

const customElementsManifest = await bundle({
    '@acme/components': sourceFiles,
});
await writeFile(
    'custom-elements.json',
    JSON.stringify(customElementsManifest, null, 2)
);