# @quatico/websmith-api > Addon API library for the websmith compiler Latest version **0.9.0** (published 2026-03-16) · MIT license · 0 weekly downloads ## Install ```sh npm install @quatico/websmith-api pnpm add @quatico/websmith-api yarn add @quatico/websmith-api bun add @quatico/websmith-api ``` ## Health **Score 55/100 (C)** — status: stable. Positive: has types; no vulnerabilities; high quality score. Warnings: low downloads; no esm support; pre 1.0. ## Facts | | | |---|---| | Version | 0.9.0 | | Published | 2026-03-16 | | First published | 2022-05-27 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 0 | | Unpacked size | 297.1 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 4 | | Author | Quatico Solutions AG | | Maintainers | quatico-admin, jwloka | ## Links - npm: https://www.npmjs.com/package/@quatico/websmith-api - Repository: https://github.com/quatico-solutions/websmith - Homepage: https://github.com/quatico-solutions/websmith#readme - Issues: https://github.com/quatico-solutions/websmith/issues - npm.io page: https://npm.io/package/@quatico/websmith-api ## Recent versions - 0.9.0 (latest) — 2026-03-16 - 0.8.5 — 2025-11-21 - 0.8.4 — 2025-11-19 - 0.8.3 — 2025-11-19 - 0.8.2 — 2025-11-19 - 0.8.1 — 2025-11-18 - 0.8.0 — 2025-11-17 - 0.7.16 — 2025-09-05 - 0.7.15 — 2025-08-20 - 0.7.14 — 2025-08-14 - 0.7.13 — 2025-08-13 - 0.7.12 — 2025-08-10 - 0.7.11 — 2025-08-08 - 0.7.10 — 2025-08-08 - 0.7.9 — 2025-08-06 - … 30 more at https://npm.io/package/@quatico/websmith-api/versions ## README # @quatico/websmith-api The websmith API package provides interfaces and functionality to implement compiler **addons** to customize the compilation output. Compiler addons can be used to modify the compilation artifacts before, during and after the compiled output is created. Even non-script files can be created and processed in the compilation process. Use the `websmith` command with an addon: * To generate additional configuration or documentation based on the original source code, * To create additional new source files and add them to the compilation process, or * To change module dependencies with new or modified imports/exports. Compiler addons can also access all transpiled files as whole and reason about the entire compilation target. The standard API for TypeScript transformers is fully integrated, thus existing `ts.CustomTransformers` can be simply called from within an addon. For a general introduction to websmith see the [websmith github repository](https://github.com/quatico-solutions/websmith#readme). ## Getting started The websmith API package is a peer dependency of the [websmith compiler](https://github.com/quatico-solutions/websmith/tree/develop/packages/compiler#readme) and provides the interfaces and functionality to implement compiler addons. ### Installation Install the API package using pnpm: ```sh pnpm add --dev @quatico/websmith-api ``` ## Implementing compiler addons Create an directory e.g. `my-code-generator` in the `addons` folder in your project folder and add an ECMAScript module named `addon.ts`: ```typescript // ./addons/component-doc-generator/addon.ts import type { AddonContext, AddonActivator } from "@quatico/websmith-api"; import { readFileSync, writeFileSync } from "fs"; export type ComponentDocConfig = { apiCollectionPath: string; }; export const activate: AddonActivator = (ctx: AddonContext) => { // Use one of the register methods to add a generator to the compilation process. ctx.registerGenerator((fileName: string, content: string): void => { const { apiCollectionPath } = ctx.getProfileConfig(); // Collect all TypeScript files containing foo in their filename if (/\/.*Component.*\\.ts$/.test(fileName)) { writeFileSync(apiCollectionPath, readFileSync(apiCollectionPath).toString() + `\n- ${fileName}`); } }); }; ``` The `addon.ts` file must export an `activate` function implementing the `AddonActivator` interface. The `AddonActivator` type is a function that takes an `AddonContext` object as argument. You can use the `AddonContext` object to register a "generator", "processor", transformer" or "resultProcessor to the compilation process. For more information on how to implement addons, see the [write your own addon](docs/write-your-own-addon.md) documentation. ## CompilerAddon Interface Starting with websmith v0.8.6, addons can implement the `CompilerAddon` interface to declare performance optimization features: ```typescript import type { AddonContext, CompilerAddon } from "@quatico/websmith-api"; export const activate = (ctx: AddonContext) => { // Register your addon logic }; // Optional: Filter which files this addon processes export const shouldProcessFile = (filePath: string, ctx: AddonContext): boolean => { return filePath.includes("/target-directory/"); }; // Optional: Declare if addon needs TypeScript type information export const needsTypeInfo = false; // Enables 10-20x faster compilation ``` ### Performance Features - **`shouldProcessFile`**: Skip files your addon doesn't need to process, reducing overhead by 10x+ - **`needsTypeInfo`**: Opt into fast transpileModule path when type information isn't required (10-20x faster) See the [performance optimization section](docs/write-your-own-addon.md#7-performance-optimization) for detailed documentation and examples. ## Activate a compiler addon You can activate your addon by using the `--addons` command line parameter when calling the websmith compiler. Add the `--addons` parameter to the build command in the `package.json` file: ```json // ./package.json { "scripts": { "build": "websmith --addons component-doc-generator" } } ``` See the [compiler README](https://github.com/quatico-solutions/websmith/tree/develop/packages/compiler#readme) for more options on how to use addons. --- _Source: https://npm.io/package/@quatico/websmith-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._