No native modules, pod install, or Android linking steps are required. This is a pure Node.js package; Node 18 or later is recommended.

Project setup

1. Copy the source/ directory into your project root, e.g. vendor/asyncapi-generator/.

2. In your tsconfig.json add a path alias so TypeScript resolves the engine cleanly:

   {
     "compilerOptions": {
       "baseUrl": ".",
       "paths": {
         "asyncapi-generator": ["vendor/asyncapi-generator/lib/generator.js"]
       }
     }
   }
   

3. If you use Babel (e.g. with Jest), add a module resolver:

   {
     "plugins": [
       ["module-resolver", { "alias": { "asyncapi-generator": "./vendor/asyncapi-generator/lib/generator.js" } }]
     ]
   }
   

4. Set the following environment variables before running generation:

   # Optional: override the default template install directory
   export ASYNCAPI_GENERATOR_TEMPLATES_DIR=/tmp/asyncapi-templates
   # Optional: increase Node heap for large specs
   export NODE_OPTIONS="--max-old-space-size=4096"
   

5. Ensure your working directory has write access for the generator's output path. The generator writes files directly to disk.

6. Run node -e "require('./vendor/asyncapi-generator/lib/generator.js')" to confirm the module loads without errors before wiring it into your application code.

Public API

Generator

import Generator from './vendor/asyncapi-generator/lib/generator';

const generator = new Generator(
  template: string,          // template name or local path
  targetDir: string,         // output directory (absolute)
  options?: {
    templateParams?: Record<string, unknown>;
    entrypoint?: string;
    noOverwriteGlobs?: string[];
    disabledHooks?: Record<string, boolean | string | string[]>;
    output?: 'string' | 'fs';
    forceWrite?: boolean;
    install?: boolean;
    debug?: boolean;
    mapBaseUrlToFolder?: Record<string, string>;
  }
);

generator.generate(asyncapiDocument: string | object): Promise<void>;
generator.generateFromFile(asyncapiFile: string): Promise<void>;
generator.generateFromString(asyncapiString: string, parsedOptions?: object): Promise<void>;

Generator is the primary entry point. Instantiate it with a template identifier and output directory, then call one of the three generate* methods depending on whether your spec lives on disk, in memory as a string, or as a pre-parsed object.

HooksRegistry

import hooksRegistry from './vendor/asyncapi-generator/lib/hooksRegistry';

hooksRegistry.registerHook(
  hookType: string,   // e.g. 'generate:after'
  hookFn: Function
): void;

Use hooksRegistry to attach custom lifecycle callbacks—for example to copy extra assets, run formatters, or emit build manifests—after the generator writes its output files.

ConditionalGeneration

import { isFileProducingOutput } from './vendor/asyncapi-generator/lib/conditionalGeneration';

isFileProducingOutput(
  templateFile: object,
  templateConfig: object,
  asyncapiDocument: object
): boolean;

isFileProducingOutput evaluates the if predicate declared in a template's file config against the live AsyncAPI document model. Use it when building a custom render loop that needs to skip files based on spec content.

Working examples

Scenario - Generate files from a local spec file

A build script reads an AsyncAPI YAML file from disk and writes generated output to ./dist/generated.

import path from 'path';
import Generator from './vendor/asyncapi-generator/lib/generator';

async function runGeneration() {
  const generator = new Generator(
    '@asyncapi/markdown-template',
    path.resolve(__dirname, 'dist/generated'),
    {
      templateParams: { singleFile: true },
      install: true,
      forceWrite: true,
    }
  );

  await generator.generateFromFile(
    path.resolve(__dirname, 'specs/asyncapi.yaml')
  );

  console.log('Generation complete.');
}

runGeneration().catch(console.error);

Scenario - Generate from an in-memory spec string

A REST endpoint accepts an AsyncAPI document body and returns generated output without touching disk by using output: 'string'.

import Generator from './vendor/asyncapi-generator/lib/generator';

async function generateToString(specYaml: string): Promise<string> {
  const generator = new Generator(
    '@asyncapi/html-template',
    '/tmp/asyncapi-out',
    {
      output: 'string',
      forceWrite: true,
      templateParams: { singleFile: true },
    }
  );

  await generator.generateFromString(specYaml);
  // When output:'string', collected output is on generator.result
  return (generator as any).result as string;
}

export { generateToString };

Scenario - Attach a post-generation hook to copy assets

After normal generation finishes, copy a custom CSS file into the output directory.

import path from 'path';
import fs from 'fs-extra';
import Generator from './vendor/asyncapi-generator/lib/generator';
import hooksRegistry from './vendor/asyncapi-generator/lib/hooksRegistry';

const OUT_DIR = path.resolve(__dirname, 'dist/docs');

hooksRegistry.registerHook('generate:after', async () => {
  await fs.copy(
    path.resolve(__dirname, 'assets/custom.css'),
    path.join(OUT_DIR, 'custom.css')
  );
  console.log('custom.css copied.');
});

async function main() {
  const generator = new Generator('@asyncapi/html-template', OUT_DIR, {
    install: true,
    forceWrite: true,
  });
  await generator.generateFromFile(path.resolve(__dirname, 'specs/api.yaml'));
}

main().catch(console.error);

File walkthrough

• lib/generator.js - Core class wiring together parsing, template resolution, rendering, and file output. This is the single orchestrator consumers interact with.
• lib/parser.js - Thin adapter over @asyncapi/parser; returns a structured document object consumed by templates and hooks.
• lib/hooksRegistry.js - Maintains a map of hook type → array of functions; invoked at well-defined lifecycle points inside generator.js.
• lib/conditionalGeneration.js - Exports predicate logic that tests template-declared if expressions against the document model at render time.
• lib/logMessages.js - All human-readable log and error strings in one place; import here to customise messages without touching engine logic.
• lib/utils.js - Low-level helpers: safe file writes, path normalisation, glob expansion, and template directory resolution.
• lib/renderer/react.js - Implements the React render engine interface; converts JSX component trees produced by templates into file content strings.
• lib/templates/bakedInTemplates.js - Reads BakedInTemplatesList.json and resolves absolute paths for officially supported templates shipped with the engine.
• lib/templates/BakedInTemplatesList.json - Static JSON array of official template package names; edit here to add or remove first-party templates.
• lib/templates/config/loader.js - Reads a template's package.json, extracts the generator config block, and normalises defaults.
• lib/templates/config/validator.js - Runs AJV schema validation against a loaded template config; throws descriptive errors on invalid structure.
• lib/__mocks__/ - Jest manual mocks for hooksRegistry, utils, filtersRegistry, and templateConfigValidator; drop these into __mocks__ in your test tree to isolate unit tests from file I/O.
• docs/ - Authoritative documentation covering API, hooks, template authoring, React engine, parser integration, and versioning.
• scripts/build-templates.js - Monorepo-internal script; not needed outside the Turborepo workspace.

Common pitfalls and fixes

• Template not found at runtime: install: true must be set on the Generator constructor options when using npm-hosted templates; without it the engine will not attempt to fetch the package.
• forceWrite omitted on re-runs: Without forceWrite: true, the generator skips files that already exist, causing stale output; always set it in CI pipelines.
• ESM/CJS interop: lib/generator.js uses CommonJS require. If your project is "type": "module", import via createRequire or configure your bundler to treat this path as CJS.
• Hook registration order: Hooks must be registered before calling any generate* method; hooks registered after the call starts are silently ignored for that run.
• Node version below 18: The parser dependency uses fetch globals and optional chaining; running on Node 16 without --experimental-fetch will throw at parse time.
• Large spec memory exhaustion: For specs with thousands of channels, set NODE_OPTIONS="--max-old-space-size=4096" to prevent heap OOM during the template render phase.

Vibe-coding prompt template

I have copied the AsyncAPI Generator source into `vendor/asyncapi-generator/`
in my project. I also have `USAGE.md` (the integration guide) at the project root.

Using ONLY the real exports described in USAGE.md and visible in the source files
under `vendor/asyncapi-generator/lib/`, please integrate the generator into my
project step by step:

1. Install all required npm dependencies listed in USAGE.md.
2. Create a `src/generate.ts` module that exports a `runGeneration(specPath, outDir, templateName)` async function using `Generator` from `vendor/asyncapi-generator/lib/generator.js`.
3. Wire a post-generation hook using `hooksRegistry` from `vendor/asyncapi-generator/lib/hooksRegistry.js` that logs the output directory path when generation finishes.
4. Add a `generate` npm script in `package.json` that calls `src/generate.ts` via `ts-node`.
5. Write a Jest unit test in `src/__tests__/generate.test.ts` that mocks `vendor/asyncapi-generator/lib/generator.js` and asserts `generateFromFile` is called with the correct arguments.

Reference: upstream package is `generator` (AsyncAPI Generator core), source root is `vendor/asyncapi-generator/`, guide is `USAGE.md`.
Do not invent any exports not listed in USAGE.md.

License and credit

The AsyncAPI Generator is released under the Apache 2.0 License. See source/LICENSE if present, or refer to the upstream repository for the full license text. Upstream source: https://github.com/asyncapi/generator, package generator within the AsyncAPI monorepo.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.