Generator Templates#

AsyncAPI Generator supports two categories of templates: legacy standalone templates (separate repos, installed via npm) and baked-in templates (shipped directly inside the generator monorepo as of v2.8). This article focuses on the baked-in model, which is the active development path 1.

Two Template Generations#

Legacy standalone templates are separate GitHub repositories published under @asyncapi/* (e.g., @asyncapi/nodejs-template, @asyncapi/html-template). They are listed in the README and installed from npm at generation time. These repos are being progressively archived; see issue #2210 for the Node.js template successor as an example.

Baked-in templates are developed, versioned, and shipped directly inside the generator repository and exposed through the @asyncapi/generator library. They live under packages/templates/ and are transpiled with the react-sdk, landing in /lib/templates/bakedInTemplates within the published package — so they are not resolved from node_modules at runtime 2.

Directory Structure#

Baked-in templates follow a strict, opinionated path convention 3:

packages/templates/{type}/[protocol]/[target]/[stack]

Directory names use the plural form (e.g., clients), but the metadata type recorded in package.json and .ageneratorrc uses the singular form (e.g., client) 4.

Currently live templates 5:

• core-template-client-kafka-java-quarkus
• core-template-client-websocket-dart
• core-template-client-websocket-java-quarkus
• core-template-client-websocket-javascript
• core-template-client-websocket-python

docs, sdk, and config types are not yet implemented 6.

Required Files per Template#

Every template directory must contain 7:

• .ageneratorrc — generator configuration (parameters, hooks, non-renderable files, metadata, conditional generation). Do not add the generator config key manually; the build script owns that 8.
• package.json — contains the template name. Version is omitted because the template is versioned together with the generator 9.

The .ageneratorrc metadata block follows the path structure 10:

metadata:
  type: client
  protocol: websocket
  target: javascript
  stack: express # optional

Build Pipeline and Metadata Normalization#

Running npm run build triggers apps/generator/scripts/build-templates.js which:

1. Traverses packages/templates, collecting directories that have both package.json and .ageneratorrc.
2. Derives metadata from the directory path segments via getTemplateMeta().
3. Maps plural path names to singular type values via normalizeType().
4. Writes normalized metadata back to .ageneratorrc via updateAGeneratorRc() — you do not maintain metadata manually.
5. Updates template package.json names to enforce the core-template-<type>-<protocol?>-<target>-<stack?> format 11.
6. Transpiles templates with react-sdk.
7. Regenerates apps/generator/lib/templates/BakedInTemplatesList.json — the runtime registry consumed by the generator 12.

Adding a New Baked-In Template#

1. Create the directory under packages/templates/ using the correct path convention 13.
2. Add .ageneratorrc (without the generator key) and package.json 14.
3. Run npm run build — the script handles naming, metadata population, transpilation, and registry update 15.

Key References#