Template development

Note It is advised against attempting to manually template types and models from scratch using the AsyncAPI templating engines such as Nunjucks and React render engines. Instead, it is recommended to use AsyncAPI Modelina a dedicated library for model generation.

Minimum template requirements

Let's break down the minimum template requirements: the template directory and a package.json file.

You can also check Template for Generator Templates project to see show-case template based on the AsyncAPI Generator.

template directory

The template directory holds all the files that will be used for generating the output. The generator will process all the files stored in this directory.

The following code is an example of an index.js file inside the template folder.

1import { File, Text } from "@asyncapi/generator-react-sdk";
2
3export default function ({ asyncapi, params, originalAsyncAPI }) {
4  return (
5    <File name="asyncapi.md">
6      <Text>My application's markdown file.</Text>
7      <Text>App name: **{asyncapi.info().title()}**</Text>
8    </File>
9  );
10}

The above example will produce an asyncapi.md file where usage of the AsyncAPI document information (i.e. the title) is demonstrated.

package.json file

Before the generation process begins, the generator installs the template into its dependencies. A package.json file is necessary to identify the template name.

The following block shows an example package.json file that points to the React Render Engine and necessary dependencies:

1{
2  "name": "myTemplate",
3  "generator": {
4    "renderer": "react"
5  },
6  "dependencies": {
7    "@asyncapi/generator-react-sdk": "^0.2.25"
8  }
9}

Every template must depend on the @asyncapi/generator-react-sdk package, which contains a template file's basic components.

Additional configuration options

You must configure the generator's package.json file to contain JSON objects with the required parameters for template configuration, such as:

The above table lists some configuration options that help the generator achieve a specific set of tasks throughout the generation process. The generator property from 'package.json' contains all the configuration information. To learn more about template configuration and various supported parameters, read the generator configuration file.

Whenever you make a change to the package.json, make sure you perform an update by running npm install; this command synchronizes with the package-lock.json and validates the file.

package.json configuration options

The following examples show some advanced configurations that we can use in our package.json file:

1{
2  "name": "myTemplate",
3  "generator": {
4    "renderer": "react",
5    "supportedProtocols": [
6      "mqtt"
7    ]
8  },
9  "dependencies": {
10    "@asyncapi/generator-react-sdk": "^0.2.25"
11  }
12}

The above package.json file has a newly added configuration called supportedProtocols which is set to a list containing only mqtt. This configuration displays all the protocols that this template supports. You can have multiple supported protocols in our template.

For example, if you want to generate an output using the above template, you need to have an AsyncAPI document with servers that use mqtt to generate your desired output. If your AsyncAPI document has server connections with kafka, the generation process will be terminated since the only supported protocol mentioned is mqtt.

Accessing template parameters

Additionally, we can also have a configuration called parameters, which is an object with all the parameters that can be passed when generating the template:

1{
2  "name": "myTemplate",
3  "generator": {
4    "renderer": "react",
5    "supportedProtocols": [
6      "mqtt"
7    ],
8    "parameters": {
9        "version": {
10          "description": "Overrides application version under `info.version` in the AsyncAPI document.",
11          "required": false
12        }
13    }
14  },
15  "dependencies": {
16    "@asyncapi/generator-react-sdk": "^0.2.25"
17  }
18}

The default version of your application is always fetched from your AsyncAPI document. The above configuration helps the template user override the existing version with a new one on the command line.

The changes done in the template will be as follows:

Original:

<Text>App name: **{ asyncapi.info().title() }**</Text>

Newer:

1<Text>App name: **{ asyncapi.info().title() }**</Text>
2<Text>Version is: **{params.version || asyncapi.info.version()}**</Text>

Now that you have added all the configuration options, you can start the generation process using the AsyncAPI CLI. You can pass these parameters via the CLI: --param name=value or -p name=value. The above configuration helps template users override the existing version with a new version on the command line. (Example: -p version=2.0.0)

Hooks

Hooks enable templates to perform multiple tasks. You can add Hooks to your template as fractions of code. In the template, you must store it in the hooks directory under the template directory. You can also store it in other modules and external libraries or configure it inside the template. The generation process can perform multiple actions.

Templates can perform multiple actions before or after the generation process with the help of hooks.

Hooks help you change the specification version with the new version that you can pass before the generation process even begins:

1module.exports = {
2  'generate:before': ({ asyncapi, templateParams = {} }) => {
3    const version = templateParams.version || asyncapi.info().version();
4    asyncapi._json.info.version = version;
5  }
6};

This can be an even better alternative to overriding the version parameter we discussed in the previous section. A markdown document will be generated, and the AsyncAPI document passed to the generator will be returned with the overwritten version.

The updated template looks like the following:

1<Text>App name: **{ asyncapi.info().title() }**</Text>
2<Text>Version: **{asyncapi.info.version()}**</Text>