Baked-in Templates

This is a new concept introduced in generator version 2.8. The number of templates is limited and solution is still in experimental phase. It is not recommended to use them in production. Instead join us to help to improve them with your use cases and your AsyncAPI documents.

Baked-in templates are official AsyncAPI templates that are developed, versioned, and shipped directly inside the generator repository and exposed with @asyncapi/generator library.

AsyncAPI Generator supports a variety of baked-in template types for generating code, documentation, configs, and SDKs. All templates are managed under the packages/templates directory and follow a strict, opinionated directory structure for consistency and ease of maintenance.

List of baked-in templates: https://github.com/asyncapi/generator/blob/master/apps/generator/lib/templates/BakedInTemplatesList.json

Supported template types

Templates are grouped by type, which must be one of the following:

• docs (not yet implemented): Templates that generate documentation
• client: Templates that generate clients
• sdk (not yet implemented): Template that generate full sdk's
• config (not yet implemented): Template that generate configuration files

Note:
The directory name is always plural (e.g., clients), but the type recorded in metadata and package name is singular (e.g., client), except for docs.

Template directory structure

General structure

All template directories must follow this convention:

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

• type: One of docs, clients, sdks, or configs.
• protocol: (Only for clients and sdks) The protocol this template supports, e.g. websocket, http, kafka.
• target: The output language, markup, or format, e.g. javascript, python, html, yaml.
• stack: (Optional, for clients and sdks) Used for technology stack, e.g. express, quarkus.

Type-specific rules

• docs/configs:
  Path must be type/target (e.g., docs/html or configs/yaml).
• clients/sdks:
  Path must be type/protocol/target or type/protocol/target/stack (e.g., clients/websocket/javascript, sdks/kafka/java/spring).

Required files

Every template directory must include:

• .ageneratorrc: Generator specific configuration, like for example parameters
• package.json: It contains template name. Version information should not be provided as it is versioned together with the generator.

Metadata and naming conventions

Generator build runs a script that normalize metadata for baked-in templates and their naming:

• Adds/updates metadata in .ageneratorrc file. You do not have to maintain it manually.
• Validates/updates template name in package.json file of given template. The name always starts with core-template- prefix.
• Generates JSON file with list of baked in templates and stores the list inside the generator: apps/generator/lib/templates/BakedInTemplatesList.json

Example

Example information provided for template stored under packages/templates/clients/websocket/javascript/express

1# .ageneratorrc
2metadata:
3  type: client
4  protocol: websocket
5  target: javascript
6  stack: express

Package name format: core-template-client-websocket-javascript-express

Resulting entry in apps/generator/lib/templates/BakedInTemplatesList.json:

1  {
2    "name": "core-template-client-websocket-javascript-express",
3    "type": "client",
4    "protocol": "websocket",
5    "target": "javascript",
6    "stack": "express"
7  }

How to add a new baked-in template

1. Create the directory in packages/templates using the correct structure.
   • For a docs template:
     packages/templates/docs/html
   • For a clients template:
     packages/templates/clients/websocket/rust
2. Add required files:
   • .ageneratorrc (do not add generator config key as it is not needed)
   • package.json
3. Run generator's build command: npm run build

Templates exposed through generator

Templates that are exposed as part of the generator are transpiled with the react-sdk and located in published library under /lib/templates/bakedInTemplates. This means that in case of baked-in templates, they are not picked by the generator from node_modules. This way the process of generation is faster and more efficient.