-
-
Notifications
You must be signed in to change notification settings - Fork 238
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
fix: add the migration guide and nunjucks depreciation notes #1253
base: master
Are you sure you want to change the base?
Changes from 1 commit
461877d
13a3a70
1e339c7
1399f23
8dbeef8
1035a3d
347fc17
826f203
3228c57
3f5c7fd
4c5344f
4182ca5
af8cff7
cc50175
8074398
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
@@ -1,17 +1,17 @@ | ||||||||||
-- | ||||||||||
title: "Depreciation of nunjucks render engine" | ||||||||||
title: "Migration guide from nunjucks render engine" | ||||||||||
Florence-Njeri marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
weight: 170 | ||||||||||
--- | ||||||||||
|
||||||||||
# Migration Guide from nunjucks render engine to react render engine | ||||||||||
## Migration Guide from nunjucks render engine to react render engine | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. please remove
Suggested change
@Florence-Njeri @Gmin2 below you can see a preview from website, how would this document render - we would have strange duplication. |
||||||||||
|
||||||||||
## Introduction | ||||||||||
### Introduction | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
when you see other generator docs, we don't write "introduction" we just write it without heading
we can of course change it if you think it is wrong, but then it should be a followup PR that unifies approach in all generator docs |
||||||||||
|
||||||||||
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 | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. probably because of my previous comments you will have to do changes to heading sizes, and start this from "##" and update the rest as well |
||||||||||
|
||||||||||
### 1. Update package.json | ||||||||||
#### 1. Update package.json | ||||||||||
|
||||||||||
Change your template configuration in `package.json`: | ||||||||||
|
||||||||||
|
@@ -23,24 +23,29 @@ Change your template configuration in `package.json`: | |||||||||
} | ||||||||||
``` | ||||||||||
|
||||||||||
### 2. Install Dependencies | ||||||||||
#### 2. Install dependencies | ||||||||||
|
||||||||||
Install the necessary React dependencies: | ||||||||||
|
||||||||||
```bash | ||||||||||
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: | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I see nunjucks: |
||||||||||
|
||||||||||
#### 4. Basic template structure | ||||||||||
|
||||||||||
Nunjucks: | ||||||||||
```jsx | ||||||||||
```js | ||||||||||
<h1>{{ asyncapi.info().title() }}</h1> | ||||||||||
<p>{{ asyncapi.info().description() }}</p> | ||||||||||
``` | ||||||||||
|
||||||||||
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) %} | ||||||||||
<div class="channel"> | ||||||||||
<h3>{{ channel.address() }}</h3> | ||||||||||
|
@@ -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 }) { | |||||||||
<h2>Channels</h2> | ||||||||||
</Text> | ||||||||||
{asyncapi.channels().map(channel => ( | ||||||||||
<Channel key={channel.address()} channel={channel} /> | ||||||||||
<Channel channel={channel} /> | ||||||||||
))} | ||||||||||
</File> | ||||||||||
); | ||||||||||
} | ||||||||||
``` | ||||||||||
|
||||||||||
### 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 | ||||||||||
|
||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||
## 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) | ||||||||||
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) | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @Gmin2 when you apply this change, please also improve the list - as per my other comment about links |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
please rename file, the document focus not on deprecation but on migration
nunjucks-react-migration.md