diff --git a/apps/generator/docs/depreciate-nunjucks.md b/apps/generator/docs/depreciate-nunjucks.md new file mode 100644 index 000000000..ab06950ee --- /dev/null +++ b/apps/generator/docs/depreciate-nunjucks.md @@ -0,0 +1,121 @@ +--- +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) + diff --git a/apps/generator/lib/generator.js b/apps/generator/lib/generator.js index 716ee32a4..edbaa9f07 100644 --- a/apps/generator/lib/generator.js +++ b/apps/generator/lib/generator.js @@ -931,9 +931,11 @@ class Generator { async renderFile(asyncapiDocument, filePath, extraTemplateData = {}) { if (isReactTemplate(this.templateConfig)) { return await renderReact(asyncapiDocument, filePath, extraTemplateData, this.templateDir, this.templateContentDir, TRANSPILED_TEMPLATE_LOCATION, this.templateParams, this.debug, this.originalAsyncAPI); + } else { + console.warn('Deprecation Warning: Nunjucks templates are deprecated. Please migrate to React templates.'); + const templateString = await readFile(filePath, 'utf8'); + return renderNunjucks(asyncapiDocument, templateString, filePath, extraTemplateData, this.templateParams, this.originalAsyncAPI, this.nunjucks); } - const templateString = await readFile(filePath, 'utf8'); - return renderNunjucks(asyncapiDocument, templateString, filePath, extraTemplateData, this.templateParams, this.originalAsyncAPI, this.nunjucks); } /** diff --git a/apps/generator/lib/renderer/nunjucks.js b/apps/generator/lib/renderer/nunjucks.js index 410b8d945..7b2a0f51c 100644 --- a/apps/generator/lib/renderer/nunjucks.js +++ b/apps/generator/lib/renderer/nunjucks.js @@ -9,6 +9,7 @@ const nunjucksExport = module.exports; * @param {string} templateDir path */ nunjucksExport.configureNunjucks = (debug, templateDir) => { + console.warn('Deprecation Warning: Nunjucks support is being phased out. Please migrate to React templates.'); const config = {}; if (debug) config.dev = true;