Skip to content
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

Open
wants to merge 15 commits into
base: master
Choose a base branch
from
Open
Prev Previous commit
Next Next commit
resolved some comments on the PR
Gmin2 committed Sep 16, 2024
commit 1399f2306583691ee96c298d2a624a5d6abe895e
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
--
Copy link
Member

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

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please remove

Suggested change
## Migration Guide from nunjucks render engine to react render engine

@Florence-Njeri @Gmin2 below you can see a preview from website, how would this document render - we would have strange duplication.

Screenshot 2024-10-21 at 11 32 23


## Introduction
### Introduction
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Introduction

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
Copy link
Member

Choose a reason for hiding this comment

The 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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see : at the end of paragraph that indicates an example follows, but there is no example - I think it is needed

nunjucks: index.html react: index.jsorindex.html.jsoranything-you-want.js`


#### 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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You might want to consider implementing snapshot tests for your template before starting migration. This will ease the review of changes in 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 produced after you do the migration. Check the [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
### 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)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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)
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)
Suggested change
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)
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 [here](https://www.asyncapi.com/blog/react-as-generator-engine)

Copy link
Member

Choose a reason for hiding this comment

The 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