From 461877dfa30cfb61828dd019b125ea6dbc5b0385 Mon Sep 17 00:00:00 2001 From: utnim2 Date: Mon, 12 Aug 2024 01:54:00 +0530 Subject: [PATCH 1/8] added a migration guide --- apps/generator/docs/nunjucka-depreciate.md | 120 +++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 apps/generator/docs/nunjucka-depreciate.md diff --git a/apps/generator/docs/nunjucka-depreciate.md b/apps/generator/docs/nunjucka-depreciate.md new file mode 100644 index 000000000..ec5e0d05e --- /dev/null +++ b/apps/generator/docs/nunjucka-depreciate.md @@ -0,0 +1,120 @@ +-- +title: "Depreciation of nunjucks render engine" +weight: 170 +--- + +# Migration Guide from nunjucks render engine to react render engine + +## Introduction + +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. + +## Step-by-Step Migration Guide + +### 1. Update package.json + +Change your template configuration in `package.json`: + +```json +{ +"generator": { +"renderer": "react" +} +} +``` + +### 2. Install Dependencies + +Install the necessary React dependencies: + +```bash +npm install @asyncapi/generator-react-sdk +``` + +### 3. Basic Template Structure + +Nunjucks: +```jsx +

{{ asyncapi.info().title() }}

+

{{ asyncapi.info().description() }}

+``` + +React: +```jsx +import { File } from '@asyncapi/generator-react-sdk'; + +export default function({ asyncapi }) { + return ( + +

{asyncapi.info().title()}

+

{asyncapi.info().description()}

+ + ); +} +``` + +### 4. Macros + +Replace macros with React components: + +Nunjucks: +```jsx +{% macro renderChannel(channel) %} +
+

{{ channel.address() }}

+

{{ channel.description() }}

+
+{% endmacro %} + +{{ renderChannel(someChannel) }} +``` + +React: +```jsx +// components/Channel.js +import { Text } from '@asyncapi/generator-react-sdk'; + +export function Channel({ channel }) { + return ( + +
+

{channel.address()}

+

{channel.description()}

+
+ + ); +} + +// Main template +import { File, Text } from '@asyncapi/generator-react-sdk'; +import { Channel } from './components/Channel'; + +export default function({ asyncapi }) { + return ( + + +

Channels

+ + {asyncapi.channels().map(channel => ( + + ))} + + ); +} +``` + +### 5. File template + +//TODO: we can add a link to Florence docs once it is merged + +## Testing Your Migration + +After migrating, test your template thoroughly: + +1. Run the generator with 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 read why we introduced react render engine [here](https://www.asyncapi.com/blog/react-as-generator-engine) \ No newline at end of file From 13a3a70c0bcad9c5fc8b9eda1bc1be02ee32801a Mon Sep 17 00:00:00 2001 From: utnim2 Date: Mon, 12 Aug 2024 01:57:35 +0530 Subject: [PATCH 2/8] added changeset --- .changeset/depreciate-nunjucks.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/depreciate-nunjucks.md diff --git a/.changeset/depreciate-nunjucks.md b/.changeset/depreciate-nunjucks.md new file mode 100644 index 000000000..6228a8458 --- /dev/null +++ b/.changeset/depreciate-nunjucks.md @@ -0,0 +1,5 @@ +--- +"@asyncapi/generator": minor +--- + +Migration guide for nunjucks render engine to react render engine \ No newline at end of file From 1399f2306583691ee96c298d2a624a5d6abe895e Mon Sep 17 00:00:00 2001 From: utnim2 Date: Tue, 17 Sep 2024 01:32:31 +0530 Subject: [PATCH 3/8] resolved some comments on the PR --- ...a-depreciate.md => nunjucks-depreciate.md} | 43 +++++++++++-------- 1 file changed, 24 insertions(+), 19 deletions(-) rename apps/generator/docs/{nunjucka-depreciate.md => nunjucks-depreciate.md} (58%) diff --git a/apps/generator/docs/nunjucka-depreciate.md b/apps/generator/docs/nunjucks-depreciate.md similarity index 58% rename from apps/generator/docs/nunjucka-depreciate.md rename to apps/generator/docs/nunjucks-depreciate.md index ec5e0d05e..faa881eec 100644 --- a/apps/generator/docs/nunjucka-depreciate.md +++ b/apps/generator/docs/nunjucks-depreciate.md @@ -1,17 +1,17 @@ -- -title: "Depreciation of nunjucks render engine" +title: "Migration guide from nunjucks render engine" weight: 170 --- -# Migration Guide from nunjucks render engine to react render engine +## Migration Guide from nunjucks render engine to react render engine -## Introduction +### Introduction -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. +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. -## Step-by-Step Migration Guide +### Step-by-step migration guide -### 1. Update package.json +#### 1. Update package.json Change your template configuration in `package.json`: @@ -23,7 +23,7 @@ Change your template configuration in `package.json`: } ``` -### 2. Install Dependencies +#### 2. Install dependencies Install the necessary React dependencies: @@ -31,16 +31,21 @@ Install the necessary React dependencies: npm install @asyncapi/generator-react-sdk ``` -### 3. Basic Template Structure +#### 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: -```jsx +```js

{{ asyncapi.info().title() }}

{{ asyncapi.info().description() }}

``` React: -```jsx +```js import { File } from '@asyncapi/generator-react-sdk'; export default function({ asyncapi }) { @@ -53,12 +58,12 @@ export default function({ asyncapi }) { } ``` -### 4. Macros +#### 5. Macros Replace macros with React components: Nunjucks: -```jsx +```js {% macro renderChannel(channel) %}

{{ channel.address() }}

@@ -70,7 +75,7 @@ Nunjucks: ``` React: -```jsx +```js // components/Channel.js import { Text } from '@asyncapi/generator-react-sdk'; @@ -96,25 +101,25 @@ export default function({ asyncapi }) {

Channels

{asyncapi.channels().map(channel => ( - + ))} ); } ``` -### 5. File template +#### 6. File template //TODO: we can add a link to Florence docs once it is merged -## Testing Your Migration +### Testing your migration After migrating, test your template thoroughly: -1. Run the generator with your new React template +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 +### Conclusion -Migrating from Nunjucks to React templates may require some initial effort, but it will result in more maintainable. You can read why we introduced react render engine [here](https://www.asyncapi.com/blog/react-as-generator-engine) \ No newline at end of file +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) \ No newline at end of file From 1035a3d449c16bfa0de912afcfdb8ec7b60131d7 Mon Sep 17 00:00:00 2001 From: utnim2 Date: Tue, 17 Sep 2024 01:37:01 +0530 Subject: [PATCH 4/8] fixed some more --- apps/generator/docs/nunjucks-depreciate.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/apps/generator/docs/nunjucks-depreciate.md b/apps/generator/docs/nunjucks-depreciate.md index faa881eec..56caabb2e 100644 --- a/apps/generator/docs/nunjucks-depreciate.md +++ b/apps/generator/docs/nunjucks-depreciate.md @@ -23,6 +23,8 @@ Change your template configuration in `package.json`: } ``` +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: @@ -32,6 +34,7 @@ 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: From 347fc17d4467effb3c19b2e1d8ddf22e513d4d64 Mon Sep 17 00:00:00 2001 From: utnim2 Date: Wed, 18 Sep 2024 13:23:13 +0530 Subject: [PATCH 5/8] added some more reviewed changes --- apps/generator/docs/nunjucks-depreciate.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/apps/generator/docs/nunjucks-depreciate.md b/apps/generator/docs/nunjucks-depreciate.md index 56caabb2e..da947d403 100644 --- a/apps/generator/docs/nunjucks-depreciate.md +++ b/apps/generator/docs/nunjucks-depreciate.md @@ -7,7 +7,7 @@ weight: 170 ### 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. +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 @@ -115,6 +115,17 @@ export default function({ asyncapi }) { //TODO: we can add a link to Florence docs once it is merged +### 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: From 3f5c7fd74453dd1e2cde4a7da6253392659e110b Mon Sep 17 00:00:00 2001 From: utnim2 Date: Thu, 10 Oct 2024 14:42:30 +0530 Subject: [PATCH 6/8] updated the required changes as reviewed --- README.md | 3 ++- apps/generator/docs/file-templates.md | 2 ++ apps/generator/docs/nunjucks-depreciate.md | 4 ++-- apps/generator/docs/nunjucks-render-engine.md | 1 + apps/generator/lib/filtersRegistry.js | 4 ++++ apps/generator/lib/renderer/nunjucks.js | 3 ++- 6 files changed, 13 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 5fe3c6018..79eaa1cae 100644 --- a/README.md +++ b/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) diff --git a/apps/generator/docs/file-templates.md b/apps/generator/docs/file-templates.md index 7a7a8ce77..a9ac23c27 100644 --- a/apps/generator/docs/file-templates.md +++ b/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. diff --git a/apps/generator/docs/nunjucks-depreciate.md b/apps/generator/docs/nunjucks-depreciate.md index da947d403..7c3f77fc6 100644 --- a/apps/generator/docs/nunjucks-depreciate.md +++ b/apps/generator/docs/nunjucks-depreciate.md @@ -61,7 +61,7 @@ export default function({ asyncapi }) { } ``` -#### 5. Macros +#### 5. Macros and Partials Replace macros with React components: @@ -113,7 +113,7 @@ export default function({ asyncapi }) { #### 6. File template -//TODO: we can add a link to Florence docs once it is merged +The detailed guide on file template can be found in [this](file-templates.md) guide. ### Additional Resources and Information diff --git a/apps/generator/docs/nunjucks-render-engine.md b/apps/generator/docs/nunjucks-render-engine.md index 34626b49b..4c7cdbe21 100644 --- a/apps/generator/docs/nunjucks-render-engine.md +++ b/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 diff --git a/apps/generator/lib/filtersRegistry.js b/apps/generator/lib/filtersRegistry.js index 6659960ed..53406b1b5 100644 --- a/apps/generator/lib/filtersRegistry.js +++ b/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. diff --git a/apps/generator/lib/renderer/nunjucks.js b/apps/generator/lib/renderer/nunjucks.js index 410b8d945..c1c6086be 100644 --- a/apps/generator/lib/renderer/nunjucks.js +++ b/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 From 4182ca5e3a08487f26cd8414ae9f728bb1a4fb6b Mon Sep 17 00:00:00 2001 From: utnim2 Date: Thu, 10 Oct 2024 14:45:59 +0530 Subject: [PATCH 7/8] changeset to major --- .changeset/depreciate-nunjucks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/depreciate-nunjucks.md b/.changeset/depreciate-nunjucks.md index 6228a8458..257bc9685 100644 --- a/.changeset/depreciate-nunjucks.md +++ b/.changeset/depreciate-nunjucks.md @@ -1,5 +1,5 @@ --- -"@asyncapi/generator": minor +"@asyncapi/generator": major --- Migration guide for nunjucks render engine to react render engine \ No newline at end of file From af8cff7b9fceae9730dd1fbcb62e4a7d053a6f77 Mon Sep 17 00:00:00 2001 From: Florence Njeri <40742916+Florence-Njeri@users.noreply.github.com> Date: Mon, 14 Oct 2024 02:31:47 -0400 Subject: [PATCH 8/8] Apply suggestions from code review Hey @Gmin2, I have left a few suggestions. Please try and run the docs in Grammarly to catch some of the spelling mistakes --- .changeset/depreciate-nunjucks.md | 2 +- README.md | 2 +- apps/generator/docs/file-templates.md | 4 ++-- apps/generator/docs/nunjucks-depreciate.md | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.changeset/depreciate-nunjucks.md b/.changeset/depreciate-nunjucks.md index 257bc9685..defb5e224 100644 --- a/.changeset/depreciate-nunjucks.md +++ b/.changeset/depreciate-nunjucks.md @@ -2,4 +2,4 @@ "@asyncapi/generator": major --- -Migration guide for nunjucks render engine to react render engine \ No newline at end of file +Migrating from Nunjucks render engine to React render engine \ No newline at end of file diff --git a/README.md b/README.md index 79eaa1cae..11745b47b 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ 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) [!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) +Deprecation Notice: The Nunjucks renderer engine is deprecated and will be removed in 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) diff --git a/apps/generator/docs/file-templates.md b/apps/generator/docs/file-templates.md index a9ac23c27..3bdda56af 100644 --- a/apps/generator/docs/file-templates.md +++ b/apps/generator/docs/file-templates.md @@ -5,9 +5,9 @@ weight: 140 ## 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**: This section applies only to the Nunjucks render engine. For information on using the React render engine, please look at 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. +> **Note**: Nunjucks renderer engine will be deprecated 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: diff --git a/apps/generator/docs/nunjucks-depreciate.md b/apps/generator/docs/nunjucks-depreciate.md index 7c3f77fc6..8c932c018 100644 --- a/apps/generator/docs/nunjucks-depreciate.md +++ b/apps/generator/docs/nunjucks-depreciate.md @@ -1,5 +1,5 @@ -- -title: "Migration guide from nunjucks render engine" +title: "Migrating from Nunjucks to React render engine" weight: 170 --- @@ -23,7 +23,7 @@ Change your template configuration in `package.json`: } ``` -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 +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