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.

完全なインストールガイドと統合プロンプトは購入後に解放されます。