@asyncapi/generator 2.4.1 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @asyncapi/generator
 
+## 2.6.0
+
+### Minor Changes
+
+- fd5dfd7: - **Deprecation of `ag` CLI**: The `ag` CLI is deprecated in favour of the `AsyncAPI CLI` that is a single entry point for all the AsyncAPI tools. No new features will be added to `ag` and it will be completely removed. The official documentation of AsyncAPI Generator has not mentioned `ag` for over a year, instead only using `AsyncAPI CLI` and `asyncapi generate fromTemplate` commands. Refer to the [migration guide](https://www.asyncapi.com/docs/tools/generator/migration-cli) that will help you understand how to migrate your `ag` commands to the new `AsyncAPI CLI` command.
+
+  - **Deprecation of Nunjucks render engine:** The [Nunjucks render engine](https://www.asyncapi.com/docs/tools/generator/nunjucks-render-engine) is deprecated and will be removed in October 2025. It is recommended to switch to the [React render engine](https://www.asyncapi.com/docs/tools/generator/react-render-engine) instead. If you are using Nunjucks in production, read the [migration guide](https://www.asyncapi.com/docs/tools/generator/migration-nunjucks-react) that will help you understand how to migrate to the new engine. The removal of the Nunjucks render engine results also in removal of [Nunjucks-filters](apps/nunjucks-filters) library.
+
+  Removal of both deprecated parts of the generator is planned for October 2025, which gives you 9 months to migrate.
+
+## 2.5.0
+
+### Minor Changes
+
+- 2d16234: - Package `@asyncapi/generator-hooks` is now part of `generator` repo and won't be released separately. Theource code is stored under `apps/hooks` but the `package/library` name stays as it was originally for backward compatibility,
+  - By default, the `@asyncapi/generator-hooks` package, known as **package** contains many different hooks used in templates and is available in the generator. You no longer have to configure it in your `package.json` in `dependencies`. The package, `@asyncapi/generator-hooks` will no longer be published to NPM separately and is deprecated. You can still have your own hooks, store them in a separate package, and configure them with your template.
+  - Remember that the fact that the hooks package is now included by default, doesn't mean all hooks from it are enabled by default. You still have to enable a given hook in the configuration file explicitly because some hooks can execute automatically without passing a specific parameter. Also, a hook's supported parameters need to be defined in your template's config.
+
 ## 2.4.1
 
 ### Patch Changes

package/cli.js

@@ -89,10 +89,17 @@ program
   .option('-o, --output <outputDir>', 'directory where to put the generated files (defaults to current directory)', parseOutput, process.cwd())
   .option('-p, --param <name=value>', 'additional param to pass to templates', paramParser)
   .option('--force-write', 'force writing of the generated files to given directory even if it is a git repo with unstaged files or not empty dir (defaults to false)')
+  .option('--disable-warning', 'disable "ag" deprecation warning (defaults to false)')
   .option('--watch-template', 'watches the template directory and the AsyncAPI document, and re-generate the files when changes occur. Ignores the output directory. This flag should be used only for template development.')
   .option('--map-base-url <url:folder>','maps all schema references from base url to local folder',mapBaseUrlParser)
   .parse(process.argv);
 
+if (!program.disableWarning) {
+  console.warn(yellow(
+    'Warning: The "ag" CLI is deprecated and will be removed in a future release. Please use the AsyncAPI CLI instead. See release notes for details: https://github.com/asyncapi/generator/releases/tag/%40asyncapi%2Fgenerator%402.6.0. You can hide this working using --disable-warning flag.')
+  );
+}
+
 if (!asyncapiDocPath) {
   console.error(red('> Path or URL to AsyncAPI file not provided.'));
   program.help(); // This exits the process

package/docs/api.md

@@ -13,6 +13,7 @@ Reference API documentation for AsyncAPI Generator library.
 * [Generator](#Generator)
     * [new Generator(templateName, targetDir, options)](#new_Generator_new)
     * _instance_
+        * [.compile](#Generator+compile) : `Boolean`
         * [.registry](#Generator+registry) : `Object`
         * [.templateName](#Generator+templateName) : `String`
         * [.targetDir](#Generator+targetDir) : `String`
@@ -38,9 +39,9 @@ Reference API documentation for AsyncAPI Generator library.
         * [.executeAfterHook()](#Generator+executeAfterHook) ⇒ `Promise.<void>`
         * [.parseInput()](#Generator+parseInput)
         * [.configureTemplate()](#Generator+configureTemplate)
-        * ~~[.generateFromString(asyncapiString, [parseOptions])](#Generator+generateFromString) ⇒ `Promise`~~
-        * [.generateFromURL(asyncapiURL)](#Generator+generateFromURL) ⇒ `Promise`
-        * [.generateFromFile(asyncapiFile)](#Generator+generateFromFile) ⇒ `Promise`
+        * ~~[.generateFromString(asyncapiString, [parseOptions])](#Generator+generateFromString) ⇒ `Promise.<(TemplateRenderResult|undefined)>`~~
+        * [.generateFromURL(asyncapiURL)](#Generator+generateFromURL) ⇒ `Promise.<(TemplateRenderResult|undefined)>`
+        * [.generateFromFile(asyncapiFile)](#Generator+generateFromFile) ⇒ `Promise.<(TemplateRenderResult|undefined)>`
         * [.installTemplate([force])](#Generator+installTemplate)
     * _static_
         * [.getTemplateFile(templateName, filePath, [templatesDir])](#Generator.getTemplateFile) ⇒ `Promise`
@@ -64,6 +65,7 @@ Instantiates a new Generator object.
     - [.forceWrite] `Boolean` ` = false` - Force writing of the generated files to given directory even if it is a git repo with unstaged files or not empty dir. Default is set to false.
     - [.install] `Boolean` ` = false` - Install the template and its dependencies, even when the template has already been installed.
     - [.debug] `Boolean` ` = false` - Enable more specific errors in the console. At the moment it only shows specific errors about filters. Keep in mind that as a result errors about template are less descriptive.
+    - [.compile] `Boolean` ` = true` - Whether to compile the template or use the cached transpiled version provided by template in '__transpiled' folder
     - [.mapBaseUrlToFolder] `Object.<String, String>` - Optional parameter to map schema references from a base url to a local base folder e.g. url=https://schema.example.com/crm/  folder=./test/docs/ .
     - [.registry] `Object` - Optional parameter with private registry configuration
         - [.url] `String` - Parameter to pass npm registry url
@@ -85,6 +87,13 @@ const generator = new Generator('@asyncapi/html-template', path.resolve(__dirnam
 });
 ```
 
+<a name="Generator+compile"></a>
+
+* generator.compile : `Boolean`** :
+Whether to compile the template or use the cached transpiled version provided by template in '__transpiled' folder.
+
+**Kind**: instance property of [`Generator`](#Generator)  
+
 <a name="Generator+registry"></a>
 
 * generator.registry : `Object`** :

package/docs/configuration-file.md

@@ -20,7 +20,7 @@ The `generator` property from `package.json` file must contain a JSON object tha
 |`nonRenderableFiles`| [String] | A list of file paths or [globs](https://en.wikipedia.org/wiki/Glob_(programming)) that must be copied "as-is" to the target directory, i.e., without performing any rendering process. This is useful when you want to copy binary files.
 |`generator`| [String] | A string representing the generator version-range the template is compatible with. This value must follow the [semver](https://nodejs.dev/learn/semantic-versioning-using-npm) syntax. E.g., `>=1.0.0`, `>=1.0.0 <=2.0.0`, `~1.0.0`, `^1.0.0`, `1.0.0`, etc. [Read more about semver](https://docs.npmjs.com/about-semantic-versioning).
 |`filters`| [String] | A list of modules containing functions that can be used as Nunjucks filters. In case of external modules, remember they need to be added as a dependency in `package.json` of your template.
-|`hooks`| Object[String, String] or Object[String, Array[String]] | A list of modules containing hooks, except for the ones you keep locally in your template in default location. For each module you must specify the exact name of the hook that should be used in the template. For a single hook you can specify it as a string, for more you must pass an array of strings. In case of external modules, remember they need to be added as a dependency in `package.json` of your template.
+|`hooks`| Object[String, String] or Object[String, Array[String]] | A list of modules containing hooks, except for the ones you keep locally in your template in the default location. For each module you must specify the exact name of the hook that should be used in the template. For a single hook, you can specify it as a string; for more hooks, you must pass an array of strings. In the case of external modules, remember they need to be added as a dependency in `package.json` of your template. There is also [an official hooks library](hooks#official-library) always included in the generator. As this is a library of multiple hooks, you still need to explicitly specify in the configuration which one you want to use. Use `@asyncapi/generator-hooks` as the library name.
 
 ### Example
 
@@ -64,7 +64,8 @@ The `generator` property from `package.json` file must contain a JSON object tha
     "my-package-with-filters"
   ],
   "hooks": {
-    "@asyncapi/generator-hooks": "hookFunctionName"
+    "@asyncapi/generator-hooks": "hookFunctionName",
+    "my-custom-hooks-package": ["myHook", "andAnotherOne"]
   }
 }
 ```

package/docs/file-templates.md

@@ -3,7 +3,13 @@ title: "File templates"
 weight: 140
 ---
 
-It is possible to generate files for each specific object in your AsyncAPI documentation. For example, you can specify a filename like `$$channel$$.js` to generate a file for each channel defined in your AsyncAPI. The following file-template names and extra variables in them are available:
+## Generating files with the Nunjucks render engine
+
+> **Note**: This section applies only to the Nunjucks render engine. For information on using the React render engine, refer to the [Generating files with the React render engine](#generating-files-with-the-react-render-engine) section below.
+
+> **Note**: Nunjucks renderer engine is deprecated and will be removed in the future. Use the React renderer engine instead. For more details read notes from release [@asyncapi/generator@2.6.0](https://github.com/asyncapi/generator/releases/tag/%40asyncapi%2Fgenerator%402.6.0).
+
+It is possible to generate files for each specific object in your AsyncAPI documentation using the Nunjucks render engine. For example, you can specify a filename like `$$channel$$.js` to generate a file for each channel defined in your AsyncAPI. The following file-template names and extra variables are available:
 
    - `$$channel$$`, within the template-file you have access to two variables [`channel`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channel) and [`channelName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channels). Where the `channel` contains the current channel being rendered.
    - `$$message$$`, within the template-file you have access to two variables [`message`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#message) and [`messageName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#message). Where `message` contains the current message being rendered.
@@ -25,7 +31,7 @@ Schema name is '{{schemaName}}' and properties are:
 {% endfor %}
 ```
 
-With following AsyncAPI:
+With the following AsyncAPI:
 ```
 components:
   schemas: 
@@ -53,15 +59,82 @@ Schema name is 'people' and properties are:
 - id
 ```
 
-### React
+> You can see an example of a file template that uses the Nunjucks render engine [here](https://github.com/asyncapi/template-for-generator-templates/tree/nunjucks/template/schemas).
+
+## Generating files with the React render engine
 
-The above way of rendering **file templates** works for both `nunjucks` and `react` render engines, but `react` also has another, more generic way to render multiple files. It is enough to return an array of `File` components in the rendering component. See the following example:
+The above method of rendering **file templates** only works for the Nunjucks render engine. To use the React render engine, you need to follow a different approach. The React render engine allows for a more generic way to render multiple files by returning an array of `File` components in the rendering component. This can be particularly useful for complex templates or when you need to generate a large number of files with varying content.
+
+### Example 1: Rendering hardcoded files
+
+The following is a simple hardcoded example of how to render multiple files using the React render engine:
 
 ```tsx
+import { File} from "@asyncapi/generator-react-sdk";
+
 export default function({ asyncapi }) {
   return [
     <File name={`file1.html`}>Content</File>,
     <File name={`file2.html`}>Content</File>
   ]
 }
-```
+```
+
+### Example 2: Rendering files based on the AsyncAPI Schema
+
+In practice, to render the multiple files, that are generated from the data defined in your AsyncAPI, you'll iterate over the array of schemas and generate a file for each schema as shown in the example below:
+
+```js
+import { File} from "@asyncapi/generator-react-sdk";
+
+/*
+ * To render multiple files, it is enough to return an array of `File` components in the rendering component, like in following example.
+ */
+export default function({ asyncapi }) {
+  const schemas = asyncapi.allSchemas();
+  const files = [];
+  // schemas is an instance of the Map
+  schemas.forEach((schema) => {
+    
+    files.push(
+      // We return a react file component and each time we do it, the name of the generated file will be a schema name
+      // Content of the file will be a variable representing schema
+      <File name={`${schema.id()}.js`}>
+        const { schema.id() } = { JSON.stringify(schema._json, null, 2) }
+      </File>
+    );
+  });
+  return files;
+}
+```
+
+### Example 3: Rendering files for each channel
+
+Additionally, you can generate multiple files for each channel defined in your AsyncAPI specification using the React render engine as shown in the example below:
+
+```js
+import { File, Text } from "@asyncapi/generator-react-sdk";
+
+
+export default function ({ asyncapi }) {
+  const files = [];
+
+  // Generate files for channels
+  asyncapi.channels().forEach((channel) => {
+    const channelName = channel.id();
+
+    files.push(
+      <File name={`${channelName}.md`}>
+        <Text newLines={2}># Channel: {channelName}</Text>
+        <Text>
+          {channel.hasDescription() && `${channel.description()}`}
+        </Text>
+      </File>
+    );
+  });
+  return files;
+}
+```
+The code snippet above uses the `Text` component to write file content to the `.md` markdown file. The `newline` property is used to ensure that the content isn't all rendered in one line in the markdown file. In summary, the code snippet above is a practical guide on generating properly formatted multiline Markdown files for each channel in an AsyncAPI document.
+
+> You can see an example of a file template that uses the React render engine [here](https://github.com/asyncapi/template-for-generator-templates/blob/master/template/schemas/schema.js).

package/docs/generator-template.md

@@ -159,7 +159,7 @@ To see this in action, navigate to the **python-mqtt-client-template** directory
 
 ``` cmd
 Generation in progress. Keep calm and wait a bit... done
-Check out your shiny new generated files at output.
+Check out your shiny new generated files at test/project.
 ```
 
 Navigating to the **test/project** directory. You should see a **client.py** file; the only content is `Temperature Service`.

package/docs/hooks.md

@@ -4,21 +4,26 @@ weight: 130
 ---
 
 Hooks are functions called by the generator on a specific moment in the generation process. Hooks can be anonymous functions but you can also add function names. These hooks can have arguments provided to them or being expected to return a value.
+
+## Types
+
 The following types of hooks are currently supported:
 
 |Hook type|Description| Return type | Arguments 
 |---|---|---|---|
-| `generate:before` | Called after registration of all filters and before the generator starts processing of the template. | void : Nothing is expected to be returned. | [The generator instance](https://github.com/asyncapi/generator/blob/master/docs/api.md)
-| `generate:after` | Called at the very end of the generation. | void : Nothing is expected to be returned. | [The generator instance](https://github.com/asyncapi/generator/blob/master/docs/api.md)
-| `setFileTemplateName ` | Called right before saving a new file generated by [file template](./file-templates.md). | string : a new filename for the generator to use for the file template. | [The generator instance](https://github.com/asyncapi/generator/blob/master/docs/api.md) and object in the form of `{ "originalFilename" : string }`
+| `generate:before` | Called after registration of all filters and before the generator starts processing of the template. | void : Nothing is expected to be returned. | [The generator instance](/api)
+| `generate:after` | Called at the very end of the generation. | void : Nothing is expected to be returned. | [The generator instance](/api)
+| `setFileTemplateName ` | Called right before saving a new file generated by [file template](./file-templates.md). | string : a new filename for the generator to use for the file template. | [The generator instance](/api) and object in the form of `{ "originalFilename" : string }`
+
+## Location
 
 The generator parses:
 - All the files in the `.hooks` directory inside the template.
-- All modules listed in the template configuration and triggers only hooks that names were added to the config. You can use the official AsyncAPI [hooks library](https://github.com/asyncapi/generator-hooks). To learn how to add hooks to configuration [read more about the configuration file](https://www.asyncapi.com/docs/tools/generator/configuration-file).
+- All modules listed in the template configuration and triggers only hooks whose names were added to the config. You can use an [official hooks library](#official-library) that is bundled together with the generator. To learn how to add hooks to configuration [read more about the configuration file](configuration-file).
 
-### Examples
+## Examples
 
-> Some of the examples have names of hook functions provided and some not. Keep in mind that hook functions kept in template in default location do not require a name. Name is required only if you keep hooks in non default location or in a separate library, because such hooks need to be explicitly configured in the configuration file. For more details on hooks configuration [read more about the configuration file](https://www.asyncapi.com/docs/tools/generator/configuration-file).
+> Some of the examples have names of hook functions provided and some not. Keep in mind that hook functions kept in template in default location do not require a name. Name is required only if you keep hooks in non default location or in a separate library, because such hooks need to be explicitly configured in the configuration file. For more details on hooks configuration [read more about the configuration file](configuration-file).
 
 Most basic modules with hooks look like this:
 ```js
@@ -79,3 +84,35 @@ module.exports = {
 	};
 };
 ```
+
+## Official library
+
+It is a library of reusable hooks that you can use in your templates. You only have to add its name to the configuration: `@asyncapi/generator-hooks` and specify which hook you want to enable.
+
+This library consists of the following hooks:
+|Hook name|Hook type|Description|
+|---|---|---|
+| `createAsyncapiFile` | `generate:after` | It creates an AsyncAPI file with the content of the spec file passed to the generator. By default, it creates the file in the root of the generation output directory. This hook also supports custom parameters that the user can pass to template generation. The parameter called `asyncapiFileDir` allows the user to specify the location where the spec file should be created. To make your template users use this parameter, you need to add it to the configuration of your template like other parameters |
+
+1. In your template configuration in `package.json` specify you want to use this library and what hook exactly:
+    ```json
+    {
+      "generator": {
+          "hooks": {
+              "@asyncapi/generator-hooks": "createAsyncapiFile"
+          }
+      }
+    }
+    ```
+1. Some hooks support custom parameters that template's user can use to specify different behaviour of the hook. To enable these, you need to also add them to the list of your template's parameters:
+    ```json
+    {
+      "generator": {
+          "parameters": {
+            "asyncapiFileDir": {
+                "description": "This template by default also outputs the AsyncAPI document that was passed as input. You can specify with this parameter what should be the location of this AsyncAPI document, relative to specified template output."
+            }
+        }
+      }
+    }
+    ```

package/docs/migration-cli.md

@@ -0,0 +1,70 @@
+---
+title: "Migrating from `ag` CLI to AsyncAPI CLI"
+weight: 260
+---
+
+This guide provides detailed instructions on how to transition from the old `ag` Generator CLI  to the new AsyncAPI CLI.
+
+## Options Overview
+
+Here is a list of `ag` options and their equivalents in the AsyncAPI CLI:
+
+- **-d, --disable-hook [hooks...]**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --disable-hook <hookType>=<hookName>`
+
+- **--debug**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --debug`
+
+- **-i, --install**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --install`
+
+- **-n, --no-overwrite <glob>**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --no-overwrite <glob>`
+
+- **-o, --output <outputDir>**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --output <outputDir>`
+
+- **-p, --param <name=value>**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --param <name=value>`
+
+- **--force-write**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --force-write`
+
+- **--watch-template**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --watch`
+
+- **--map-base-url <url:folder>**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --map-base-url <url:folder>`
+
+## Migration Steps
+
+### 1. Install AsyncAPI CLI
+
+There are multiple different artifacts that AsyncAPI CLI is provided as. Get familiar with the [official CLI installation guide](https://www.asyncapi.com/docs/tools/cli/installation).
+
+### 2. Update Your Commands
+
+Replace the deprecated `ag` commands with the AsyncAPI CLI equivalents. Below are examples of how to update your commands:
+
+**Using `ag`**:
+```
+ag ./asyncapi.yaml ./template -o ./output -p param1=value1 --debug --install --disable-hook hookType=hookName
+```
+
+**Using AsyncAPI CLI**:
+```
+asyncapi generate fromTemplate ./asyncapi.yaml ./template -o ./output -p param1=value1 --debug --install --disable-hook hookType=hookName
+```
+
+Notice that the change basically related to changing from `ag` to `asyncapi generate fromTemplate`.
+
+### 3. Verify and Test
+
+Run the updated commands to ensure they work as expected and verify that the output files are generated correctly.
+
+## Additional Resources
+
+**CLI Documentation**: [AsyncAPI CLI Documentation](https://www.asyncapi.com/docs/tools/cli)
+**Installation**: [AsyncAPI CLI Installation](https://www.asyncapi.com/docs/tools/cli/installation)
+**Usage**: [AsyncAPI CLI Usage](https://www.asyncapi.com/docs/tools/cli/usage)
+**Support**: For any issues with CLI, create an issue in [CLI repository](https://github.com/asyncapi/cli).

package/docs/migration-nunjucks-react.md

@@ -0,0 +1,144 @@
+---
+title: "Migrating from Nunjucks to React render engine"
+weight: 250
+---
+
+The AsyncAPI Generator is moving away from Nunjucks templates in favor of React templates. This guide will help you migrate your existing Nunjucks templates to React. For a comprehensive understanding of why we introduced React as an alternative in 2021 and why we're now removing Nunjucks entirely, please read our article [React as a Generator Engine](https://www.asyncapi.com/blog/react-as-generator-engine). The principles discussed in this article still apply to our current transition.
+
+## Step-by-step migration guide
+
+### 1. Update package.json
+
+Change your template configuration in `package.json`:
+
+```json
+{
+"generator": {
+"renderer": "react"
+}
+}
+```
+
+Once the deprecation period has ended, and we remove the default Nunjucks, the React render engine will be used by default and this setting will no longer be needed to configure
+
+### 2. Install dependencies
+
+Install the necessary React dependencies:
+
+```bash
+npm install @asyncapi/generator-react-sdk
+```
+
+### 3. File naming
+
+In Nunjucks, the template's filename directly corresponds to the output file. For example, a template named **index.html** will generate an **index.html** file.
+
+In React, the filename of the generated file is not controlled by the file itself, but rather by the `File` component. The React component itself can be named anything with a `.js` extension because the output filename is controlled by the `name` attribute of the `File` component used inside the template file. Below you can see some examples of filenames: 
+
+Nunjucks: `index.html`
+React: `index.js` or `index.html.js` or `anything-you-want.js`
+
+### 4. Basic template structure
+
+Nunjucks:
+```js
+<h1>{{ asyncapi.info().title() }}</h1>
+<p>{{ asyncapi.info().description() }}</p>
+```
+
+React:
+```js
+import { File } from '@asyncapi/generator-react-sdk';
+
+export default function({ asyncapi }) {
+  return (
+    <File name="index.html">
+      <h1>{asyncapi.info().title()}</h1>
+      <p>{asyncapi.info().description()}</p>
+    </File>
+  );
+}
+```
+
+### 5. Macros and Partials
+
+Replace macros with React components:
+
+Nunjucks:
+```js
+{% macro renderChannel(channel) %}
+  <div class="channel">
+    <h3>{{ channel.address() }}</h3>
+    <p>{{ channel.description() }}</p>
+  </div>
+{% endmacro %}
+
+{{ renderChannel(someChannel) }}
+```
+
+React:
+```js
+// components/Channel.js
+import { Text } from '@asyncapi/generator-react-sdk';
+
+export function Channel({ channel }) {
+  return (
+    <Text>
+      <div className="channel">
+        <h3>{channel.address()}</h3>
+        <p>{channel.description()}</p>
+      </div>
+    </Text>
+  );
+}
+
+// Main template
+import { File, Text } from '@asyncapi/generator-react-sdk';
+import { Channel } from './components/Channel';
+
+export default function({ asyncapi }) {
+  return (
+    <File name="channels.html">
+      <Text>
+        <h2>Channels</h2>
+      </Text>
+      {asyncapi.channels().map(channel => (
+        <Channel channel={channel} />
+      ))}
+    </File>
+  );
+}
+```
+
+### 6. File template 
+
+Check the [detailed guide on file templates](file-templates.md) to learn what is the difference between templating multiple file outputs in Nunjucks and React.
+
+### 7. Models generation
+
+If you have a template written with Nunjucks, it is almost certain that you have your own custom models, classes, or types templates in place. Instead of migrating them to React render engine we strongly advise you to delegate models generation to AsyncAPI Modelina project. Learn more about [how to add models generation using Modelina](https://www.asyncapi.com/docs/tools/generator/model-generation).
+
+## Additional Resources and Information
+
+### Template Examples
+For a complete example of React features in use, please refer to the [AsyncAPI Template for Generator Templates](https://github.com/asyncapi/template-for-generator-templates). The `master` branch demonstrates all React features, while the `nunjucks` branch shows the old Nunjucks implementation. This comparison can be particularly helpful in understanding the differences and migration process.
+
+### Filters to Helpers
+If you've been using Nunjucks filters placed in the `filters` directory, you can still use this functionality in React. However, they should be treated as normal functions that you import into your components. We recommend renaming the `filters` directory to `helpers` to better reflect their new usage in React.
+
+### Hooks Remain Unchanged
+It's important to note that hooks remain unchanged in this migration process. Hooks are not related to the render engine functionality, so you can continue to use them as you have been.
+
+### Testing your migration
+
+After migrating, test your template thoroughly:
+
+1. Run the generator using your new React template
+2. Compare the output with the previous Nunjucks template output
+3. Check for any missing or incorrectly rendered content
+
+Consider implementing snapshot tests for your template before starting the migration. This will ease the review of changes in comparing the content rendered after render engine changes. Snapshot tests allow you to have tests that will persist expected output from Nunjucks template, and compare it with output generated after the migration. Check out an [example of such snapshot integration test for our internal react template we use for development and testing](https://github.com/asyncapi/generator/blob/master/apps/generator/test/integration.test.js#L66).
+
+## Conclusion
+
+Migrating from Nunjucks to React templates may require some initial effort, but it will result in more maintainable code. You can learn more about why we introduced the React render engine from article [React as a Generator Engine](https://www.asyncapi.com/blog/react-as-generator-engine).

package/docs/nunjucks-render-engine.md

@@ -3,6 +3,8 @@ title: "Nunjucks render engine"
 weight: 120
 ---
 
+> **Note**: Nunjucks renderer engine is deprecated and will be removed in the future. Use the React renderer engine instead. For more details read notes from release [@asyncapi/generator@2.6.0](https://github.com/asyncapi/generator/releases/tag/%40asyncapi%2Fgenerator%402.6.0).
+
 [Nunjucks](https://mozilla.github.io/nunjucks) is the default render engine, however, we strongly recommend adopting the [React](#react) engine.
 
 ### Common assumptions

package/lib/filtersRegistry.js

@@ -6,6 +6,7 @@ const nunjucksFilters = require('@asyncapi/nunjucks-filters');
 
 /**
  * Registers all template filters.
+ * @deprecated This method is deprecated. For more details, see the release notes: https://github.com/asyncapi/generator/releases/tag/%40asyncapi%2Fgenerator%402.6.0
  * @param {Object} nunjucks Nunjucks environment.
  * @param {Object} templateConfig Template configuration.
  * @param {String} templateDir Directory where template is located.
@@ -21,6 +22,7 @@ module.exports.registerFilters = async (nunjucks, templateConfig, templateDir, f
 
 /**
  * Registers the local template filters.
+ * @deprecated This method is deprecated. For more details, see the release notes: https://github.com/asyncapi/generator/releases/tag/%40asyncapi%2Fgenerator%402.6.0
  * @private
  * @param {Object} nunjucks Nunjucks environment.
  * @param {String} templateDir Directory where template is located.
@@ -68,6 +70,7 @@ function registerLocalFilters(nunjucks, templateDir, filtersDir) {
 
 /**
  * Registers the additionally configured filters.
+ * @deprecated This method is deprecated. For more details, see the release notes: https://github.com/asyncapi/generator/releases/tag/%40asyncapi%2Fgenerator%402.6.0
  * @private
  * @param {Object} nunjucks Nunjucks environment.
  * @param {String} templateDir Directory where template is located.
@@ -112,6 +115,7 @@ async function registerConfigFilters(nunjucks, templateDir, templateConfig) {
 
 /**
  * Add filter functions to Nunjucks environment. Only owned functions from the module are added.
+ * @deprecated This method is deprecated. For more details, see the release notes: https://github.com/asyncapi/generator/releases/tag/%40asyncapi%2Fgenerator%402.6.0
  * @private
  * @param {Object} nunjucks Nunjucks environment.
  * @param {Object} filters Module with functions.

package/lib/generator.js

@@ -134,7 +134,7 @@ class Generator {
       Object.defineProperty(this.templateParams, key, {
         enumerable: true,
         get() {
-          if (!self.templateConfig.parameters || !self.templateConfig.parameters[key]) {
+          if (!self.templateConfig.parameters?.[key]) {
             throw new Error(`Template parameter "${key}" has not been defined in the package.json file under generator property. Please make sure it's listed there before you use it in your template.`);
           }
           return templateParams[key];
@@ -436,7 +436,7 @@ class Generator {
    * @param  {String} asyncapiString AsyncAPI string to use as source.
    * @param  {Object} [parseOptions={}] AsyncAPI Parser parse options. Check out {@link https://www.github.com/asyncapi/parser-js|@asyncapi/parser} for more information.
    * @deprecated Use the `generate` function instead. Just change the function name and it works out of the box.
-   * @return {Promise}
+   * @return {Promise<TemplateRenderResult|undefined>}
    */
   async generateFromString(asyncapiString, parseOptions = {}) {
     const isParsableCompatible = asyncapiString && typeof asyncapiString === 'string';
@@ -466,7 +466,7 @@ class Generator {
    * }
    *
    * @param  {String} asyncapiURL Link to AsyncAPI file
-   * @return {Promise}
+   * @return {Promise<TemplateRenderResult|undefined>}
    */
   async generateFromURL(asyncapiURL) {
     const doc = await fetchSpec(asyncapiURL);
@@ -493,7 +493,7 @@ class Generator {
    * }
    *
    * @param  {String} asyncapiFile AsyncAPI file to use as source.
-   * @return {Promise}
+   * @return {Promise<TemplateRenderResult|undefined>}
    */
   async generateFromFile(asyncapiFile) {
     const doc = await readFile(asyncapiFile, { encoding: 'utf8' });
@@ -562,8 +562,8 @@ class Generator {
 
       try {
         installedPkg = getTemplateDetails(this.templateName, PACKAGE_JSON_FILENAME);
-        pkgPath = installedPkg && installedPkg.pkgPath;
-        packageVersion = installedPkg && installedPkg.version;
+        pkgPath = installedPkg?.pkgPath;
+        packageVersion = installedPkg?.version;
         log.debug(logMessage.templateSource(pkgPath));
         if (packageVersion) log.debug(logMessage.templateVersion(packageVersion));
 
@@ -759,7 +759,7 @@ class Generator {
     // Check if the filename dictates it should be separated
     let wasSeparated = false;
     for (const prop in fileNamesForSeparation) {
-      if (Object.prototype.hasOwnProperty.call(fileNamesForSeparation, prop) && stats.name.includes(`$$${prop}$$`)) {
+      if (Object.hasOwn(fileNamesForSeparation, prop) && stats.name.includes(`$$${prop}$$`)) {
         await this.generateSeparateFiles(asyncapiDocument, fileNamesForSeparation[prop], prop, stats.name, root);
         const templateFilePath = path.relative(this.templateContentDir, path.resolve(root, stats.name));
         fs.unlink(path.resolve(this.targetDir, templateFilePath), next);
@@ -875,7 +875,7 @@ class Generator {
     const shouldOverwriteFile = await this.shouldOverwriteFile(relativeTargetFile);
     if (!shouldOverwriteFile) return;
 
-    if (this.templateConfig.conditionalFiles && this.templateConfig.conditionalFiles[relativeSourceFile]) {
+    if (this.templateConfig.conditionalFiles?.[relativeSourceFile]) {
       const server = this.templateParams.server && asyncapiDocument.servers().get(this.templateParams.server);
       const source = jmespath.search({
         ...asyncapiDocument.json(),

package/lib/logMessages.js

@@ -2,7 +2,7 @@ const TEMPLATE_INSTALL_FLAG_MSG = 'because you passed --install flag';
 
 const TEMPLATE_INSTALL_DISK_MSG = 'because the template cannot be found on disk';
 
-const NODE_MODULES_INSTALL ='Remember that your local template must have its own node_modules installed first, \"npm install\" is not triggered by the generator.';
+const NODE_MODULES_INSTALL = 'Remember that your local template must have its own node_modules installed first, "npm install" is not triggered by the generator.';
 
 const NPM_INSTALL_TRIGGER = 'Installation of template located on disk technically means symlink creation betweed node_modules of the generator and template sources. Your local template must have its own node_modules, "npm install" is not triggered.';
 
@@ -19,7 +19,7 @@ function templateNotFound(templateName) {
 }
 
 function packageNotAvailable(packageDetails) {
-  if (packageDetails && packageDetails.pkgPath) {
+  if (packageDetails?.pkgPath) {
     return `Unable to resolve template location at ${packageDetails.pkgPath}. Package is not available locally.`;
   }
 

package/lib/parser.js

@@ -63,7 +63,7 @@ function convertOldOptionsToNew(oldOptions, generator) {
   }
 
   const resolvers = [];
-  if (generator && generator.mapBaseUrlToFolder && generator.mapBaseUrlToFolder.url) {
+  if (generator?.mapBaseUrlToFolder?.url) {
     resolvers.push(...getMapBaseUrlToFolderResolvers(generator.mapBaseUrlToFolder));
   }
   if (oldOptions.resolve) {