fix: add the migration guide and nunjucks depreciation notes

.changeset/depreciate-nunjucks.md

@@ -0,0 +1,5 @@
+---
+"@asyncapi/generator": major
+---
+
+Migration guide for nunjucks render engine to react render engine

README.md

@@ -9,7 +9,8 @@ This is a Monorepo managed using [Turborepo](https://turbo.build/) and contains
 
 ![npm](https://img.shields.io/npm/v/@asyncapi/generator?style=for-the-badge) ![npm](https://img.shields.io/npm/dt/@asyncapi/generator?style=for-the-badge)
 
-> warning: This package doesn't support AsyncAPI 1.x anymore. We recommend to upgrade to the latest AsyncAPI version using the [AsyncAPI converter](https://github.com/asyncapi/converter-js) (You can refer to [installation guide](/apps/generator//docs//installation-guide.md)). If you need to convert documents on the fly, you may use the [Node.js](https://github.com/asyncapi/converter-js) or [Go](https://github.com/asyncapi/converter-go) converters.
+[!IMPORTANT]
+Deprecation Notice: The nunjucks renderer engine is depreciated and will be removed in the future releases.We strongly recommend using the react renderer engine instead, you can find how to migrate from nunjucks to react in the [migration guide](apps/generator/docs/nunjucks-depreciate.md) 
 
 <!-- toc is generated with GitHub Actions do not remove toc markers -->
 

apps/generator/docs/file-templates.md

@@ -7,6 +7,8 @@ weight: 140
 
 > **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 will be depreciated in the future release and we strongly recommend using the react renderer engine instead.
+
 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.

apps/generator/docs/nunjucks-depreciate.md

@@ -0,0 +1,139 @@
+--
+title: "Migration guide from nunjucks render engine"
+weight: 170
+---
+
+## Migration Guide from nunjucks render engine to react render engine
+
+### Introduction
+
+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 deprecation period is ended, and we remove default nunjucks engine, react will become 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, but the output file is controlled by the `name` attribute of the File component:
+
+#### 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 
+
+The detailed guide on file template can be found in [this](file-templates.md) guide.
+
+### 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
+
+### Conclusion
+
+Migrating from Nunjucks to React templates may require some initial effort, but it will result in more maintainable. You can learn more about why we introduced ther React render engine [here](https://www.asyncapi.com/blog/react-as-generator-engine)

apps/generator/docs/nunjucks-render-engine.md

@@ -4,6 +4,7 @@ weight: 120
 ---
 
 [Nunjucks](https://mozilla.github.io/nunjucks) is the default render engine, however, we strongly recommend adopting the [React](#react) engine.
+> **Note**: Nunjucks renderer engine will be depreciated in the future release and we strongly recommend using the react renderer engine instead.
 
 ### Common assumptions
 

apps/generator/lib/filtersRegistry.js

@@ -6,6 +6,7 @@ const nunjucksFilters = require('@asyncapi/nunjucks-filters');
 
 /**
  * Registers all template filters.
+ * @deprecated since version 3.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 since version 3.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 since version 3.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 since version 3.0
  * @private
  * @param {Object} nunjucks Nunjucks environment.
  * @param {Object} filters Module with functions.

apps/generator/lib/renderer/nunjucks.js

@@ -3,7 +3,7 @@ const nunjucksExport = module.exports;
 
 /**
  * Configures Nunjucks templating system
- * 
+ * @deprecated since version 3.0
  * @private
  * @param {boolean} debug flag
  * @param {string} templateDir path
@@ -18,6 +18,7 @@ nunjucksExport.configureNunjucks = (debug, templateDir) => {
 /**
  * Renders the template with nunjucks and returns a string.
  * 
+ * @deprecated since version 3.0
  * @param {import('@asyncapi/parser').AsyncAPIDocument} asyncapiDocument 
  * @param {string} templateString template filecontent to be rendered with nunjucks
  * @param {string} filePath path to the template file