diff --git a/.changeset/remove-deprecated-nunjucks-cli.md b/.changeset/remove-deprecated-nunjucks-cli.md new file mode 100644 index 0000000000..5e6b8f211e --- /dev/null +++ b/.changeset/remove-deprecated-nunjucks-cli.md @@ -0,0 +1,12 @@ +--- +"@asyncapi/generator": major +--- + +### Breaking Changes +* Nunjucks renderer removed — React is now the sole rendering engine. No need to specify render engine in config anymore +* Nunjucks filters package and its public filters removed; filter-based template APIs no longer available. +* `ag` CLI is no longer available. Long time ago it was already announced that it will be removed and people should move to [AsyncAPI CLI](https://github.com/asyncapi/cli/) + +### Migration Guides +- [Migrating from Nunjucks to React render engine](https://github.com/asyncapi/generator/blob/%40asyncapi/generator%402.8.4/apps/generator/docs/migration-nunjucks-react.md) +- [Migrating from `ag` CLI to AsyncAPI CLI](https://github.com/asyncapi/generator/blob/%40asyncapi/generator%402.8.4/apps/generator/docs/migration-cli.md) \ No newline at end of file diff --git a/Development.md b/Development.md index eebd7e7a58..c43d28ad7d 100644 --- a/Development.md +++ b/Development.md @@ -58,7 +58,7 @@ You can also opt in to run the lint checks after the tests, by setting an enviro ### Manually testing with test templates -To test template features manually we have `react-template` and `nunjucks-template` in `apps/generator/test/templates`, you can use this templates to manually test your changes like this: +To test template features manually we have `react-template` in `apps/generator/test/test-templates`, you can use this template to manually test your changes like this: 1. Navigate to the generator directory: @@ -70,7 +70,7 @@ cd apps/generator 3. Run the generator with the react-template: ```bash -node ./cli ./test/docs/dummy.yml ./test/test-templates/react-template -o ./test/output --force-write +node ./test/cli ./test/docs/dummy.yml ./test/test-templates/react-template -o ./test/output --force-write ``` 4. Check the output in the `./test/output` directory to verify the output that you desired. diff --git a/README.md b/README.md index fc6a0b8197..ac5a722962 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,10 @@ [![AsyncAPI Generator](./assets/readme-banner.png)](https://www.asyncapi.com/tools/generator) -> Some parts of the AsyncAPI Generator are deprecated and the plan is to remove them in October 2025. For more details read notes from release [@asyncapi/generator@2.6.0](https://github.com/asyncapi/generator/releases/tag/%40asyncapi%2Fgenerator%402.6.0). - This is a Monorepo managed using [Turborepo](https://turbo.build/) and contains the following package: 1. [Generator](apps/generator): This is a tool that you can use to generate whatever you want basing on the AsyncAPI specification file as an input. -1. [Hooks](apps/hooks): This library contains generator filters that can be reused across multiple templates, helping to avoid redundant work. Hooks are designed to let template developers hook into the template generation process. For example, one can create a hook code that will be automatically invoked right after the template generation process has ended. - -1. [Nunjucks-filters](apps/nunjucks-filters): This library contains generator filters that can be reused across multiple templates helping to avoid redundant work. These filters are designed specifically for Nunjucks templates and are included by default with the generator, so there's no need to add them to dependencies separately. +1. [Hooks](apps/hooks): Hooks are designed to let template developers hook into the template generation process. For example, one can create a hook code that will be automatically invoked right after the template generation process has ended. 1. [React-sdk](apps/react-sdk): AsyncAPI React SDK is a set of components/functions to use React as render engine for the generator. This is the library that undestand components from Generator's templates that are configured to use `react` render engine. @@ -16,9 +12,6 @@ This is a Monorepo managed using [Turborepo](https://turbo.build/) and contains 1. [Generator-components](packages/components): A library of reusable components that can be shared across different templates, helping to avoid duplication and accelerate template development. -> [!IMPORTANT] -> **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/migration-nunjucks-react.md) - ![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) @@ -68,18 +61,9 @@ You can find above templates and the ones provided by the community in **[this l > [!IMPORTANT] > **Experimental Feature:** AsyncAPI Generator also comes with **baked-in templates** - official templates shipped directly inside the Generator (`@asyncapi/generator`). They cover code, docs, configs, and SDKs, and are maintained under [/packages/templates](packages/templates) directory, following a strict, opinionated structure for consistency and ease of maintenance. This feature is not recommended for production use. For those who want to try them out or learn more, see the [Baked-in templates documentation](https://www.asyncapi.com/docs/tools/generator/baked-in-templates). -## Filters - - `apps/nunjucks-filters` library contains generator filters that can be reused across multiple templates, helping to avoid redundant work. These filters are designed specifically for Nunjucks templates and are included by default with the generator, so there's no need to add them to dependencies separately. - -This library consists of: - -- Custom filters. Check out [API docs](apps/nunjucks-filters/docs/api.md) for complete list -- Lodash-powered filters. For the list of all available filters check [official docs](https://lodash.com/docs/) - ## Hooks -The `apps/hooks` library contains generator filters that can be reused across multiple templates, helping to avoid redundant work. [Hooks](https://www.asyncapi.com/docs/tools/generator/hooks) are functions called by the generator at specific moments in the generation process. Hooks can be anonymous functions, but you can also assign them function names. These hooks can have arguments provided to them, or they may be expected to return a value. +[Hooks](https://www.asyncapi.com/docs/tools/generator/hooks) are functions called by the generator at specific moments in the generation process. Hooks can be anonymous functions, but you can also assign them function names. These hooks can have arguments provided to them, or they may be expected to return a value. These hooks are included in the generator without adding any specific dependency to the library. You still have to enable the given hook in the configuration explicitly because some hooks can execute automatically without passing a specific parameter. [Learn more about configuration and what hooks are available out of the box](https://www.asyncapi.com/docs/tools/generator/hooks#official-library). diff --git a/apps/generator/docs/api.md b/apps/generator/docs/api.md index fdf380f25a..d5447e313b 100644 --- a/apps/generator/docs/api.md +++ b/apps/generator/docs/api.md @@ -365,7 +365,7 @@ Parse the generator input based on the template `templateConfig.apiVersion` valu * generator.configureTemplate()** : -Configure the templates based the desired renderer. +Configure the templates. **Kind**: instance method of [`Generator`](#Generator) diff --git a/apps/generator/docs/asyncapi-document.md b/apps/generator/docs/asyncapi-document.md index ac88a721a9..de5314fa1d 100644 --- a/apps/generator/docs/asyncapi-document.md +++ b/apps/generator/docs/asyncapi-document.md @@ -21,7 +21,7 @@ In the following sections, you'll learn about the inner working of the generator 3. The **Parser** validates the **AsyncAPI Document** using additional schema-related plugins, either the OpenAPI schema, RAML data types, or Avro schema. 4. If the **Parser** determines that the **AsyncAPI Document** is valid, it manipulates the original JSON/YAML document and provides a set of helper functions in return, bundling them together into an **asyncapi** variable that is an instance of [**AsyncAPIDocument**](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#asyncapidocument). 5. At this point, the **Generator** passes the **originalAsyncAPI** and the **asyncapi** which make up part of the **[Template Context](template-context)** to the **Render Engine**. -6. The **Template Context** is accessible to the template files that are passed to either the [react](react-render-engine) or [nunjucks](nunjucks-render-engine) **Render Engines**. +6. The **Template Context** is accessible to the template files that are passed to the [react](react-render-engine) **Render Engine**. ```mermaid graph LR diff --git a/apps/generator/docs/configuration-file.md b/apps/generator/docs/configuration-file.md index a84133cd3c..49b4ee86c3 100644 --- a/apps/generator/docs/configuration-file.md +++ b/apps/generator/docs/configuration-file.md @@ -21,7 +21,6 @@ metadata: target: javascript stack: express -renderer: react apiVersion: v3 supportedProtocols: - amqp @@ -86,7 +85,6 @@ Alternatively, you can include your configuration in the `generator` property of "target": "javascript", "stack": "express" }, - "renderer": "react", "apiVersion": "v3", "supportedProtocols": ["amqp", "mqtt"], "parameters": { @@ -150,7 +148,6 @@ The `generator` property from `package.json` file must contain a JSON object and | `metadata.protocol` | String | **Required for `client`/`sdk`**. The protocol this template targets (e.g., `websocket`, `kafka`). Not used for `docs`/`config`. | | `metadata.target` | String | **Required**. The output language or format (e.g., `javascript`, `html`, `yaml`). | | `metadata.stack` | String | Optional. The stack or framework (e.g., `express`, `quarkus`). Only for `client`/`sdk`. | -| `renderer` | String | Its value can be either `react` or `nunjucks` (default). | | `apiVersion` | String | Determines which **major** version of the [Parser-API](https://github.com/asyncapi/parser-api) the template uses. For example, `v2` for `v2.x.x`. If not specified, the Generator assumes the template is not compatible with the Parser-API so it will use the [Parser-JS v1 API](https://github.com/asyncapi/parser-js/tree/v1.18.1#api-documentation). For templates that need to support AsyncAPI specification v3 make sure to use `v3` [Parser-API](https://github.com/asyncapi/parser-api). If the template uses a version of the Parser-API that is not supported by the Generator, the Generator will throw an error. | | `supportedProtocols` | [String] | A list with all the protocols this template supports. | | `parameters` | Object[String, Object] | An object with all the parameters that can be passed when generating the template. When using the command line, it's done by indicating `--param name=value` or `-p name=value`. | @@ -166,7 +163,6 @@ The `generator` property from `package.json` file must contain a JSON object and | `conditionalGeneration[filePath/directoryName].validation` | Object (JSON Schema fragment) | The validation defines the condition under which the file or directory will be generated. It must be a valid JSON Schema fragment that validates the value of the parameter. For example, if you want to include a folder only when includeDocs is true, use "validation": `{ "const": true }`. You can also use more complex validation logic, like "enum": ["yes", "true"] or "type": "string" with a "pattern" constraint. If the parameter fails validation, the file or folder will not be included in the generated output. This allows for powerful and flexible control over template generation based on user input. | | `nonRenderableFiles` | [String] | A list of file paths or [globs](https://en.wikipedia.org/wiki/Glob_(programming)) that must be copied "as-is" to the target directory, i.e., without performing any rendering process. This is useful when you want to copy binary files. | | `generator` | [String] | A string representing the generator version-range the template is compatible with. This value must follow the [semver](https://nodejs.dev/learn/semantic-versioning-using-npm) syntax. E.g., `>=1.0.0`, `>=1.0.0 <=2.0.0`, `~1.0.0`, `^1.0.0`, `1.0.0`, etc. [Read more about semver](https://docs.npmjs.com/about-semantic-versioning). | -| `filters` | [String] | A list of modules containing functions that can be used as Nunjucks filters. In case of external modules, remember they need to be added as a dependency in `package.json` of your template. | | `hooks` | Object[String, String] or Object[String, Array[String]] | A list of modules containing hooks, except for the ones you keep locally in your template in the default location. For each module you must specify the exact name of the hook that should be used in the template. For a single hook, you can specify it as a string; for more hooks, you must pass an array of strings. In the case of external modules, remember they need to be added as a dependency in `package.json` of your template. There is also [an official hooks library](hooks#official-library) always included in the generator. As this is a library of multiple hooks, you still need to explicitly specify in the configuration which one you want to use. Use `@asyncapi/generator-hooks` as the library name. | ## Special parameters diff --git a/apps/generator/docs/file-templates.md b/apps/generator/docs/file-templates.md index 2b5c05431e..1c0b858572 100644 --- a/apps/generator/docs/file-templates.md +++ b/apps/generator/docs/file-templates.md @@ -3,67 +3,9 @@ title: "File templates" 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**: Nunjucks renderer engine is deprecated and will be removed in the future. Use the React renderer engine instead. For more details read notes from release [@asyncapi/generator@2.6.0](https://github.com/asyncapi/generator/releases/tag/%40asyncapi%2Fgenerator%402.6.0). - -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. - - `$$message$$`, within the template-file you have access to two variables [`message`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#message) and [`messageName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#message). Where `message` contains the current message being rendered. - - `$$schema$$`, within the template-file you have access to two variables [`schema`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schema) and [`schemaName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schema). Where `schema` contains the current schema being rendered. Only schemas from [Components object](https://www.asyncapi.com/docs/reference/specification/latest#componentsObject) are used. - - `$$everySchema$$`, within the template-file you have access to two variables [`schema`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schema) and [`schemaName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schemas). Where `schema` contains the current schema being rendered. Every [Schema object](https://www.asyncapi.com/docs/specifications/2.0.0/#schemaObject) from the entire AsyncAPI file is used. - - `$$objectSchema$$`, within the template-file you have access to two variables [`schema`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schema) and [`schemaName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schemas). Where `schema` contains the current schema being rendered. All the [Schema objects](https://www.asyncapi.com/docs/reference/specification/latest#multiFormatSchemaObject) with type object is used. - - `$$parameter$$`, within the template-file you have access to two variables [`parameter`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channelparameter) and [`parameterName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channelparameters). Where the `parameter` contains the current parameter being rendered. - - `$$securityScheme$$`, within the template-file you have access to two variables [`securityScheme`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#securityscheme) and [`securitySchemeName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#securityschemes). Where `securityScheme` contains the current security scheme being rendered. - -The file name will be equal to `*Name` variable. - -### Example - -The file name is `$$schema$$.txt`, the content of this file is: -``` -Schema name is '{{schemaName}}' and properties are: -{% for propName, prop in schema.properties() %} -- {{prop.uid()}} -{% endfor %} -``` - -With the following AsyncAPI: -``` -components: - schemas: - peoplePayload: - type: object - properties: - event: - $ref: "#/components/schemas/people" - people: - type: object - properties: - id: - type: integer -``` - -The generator creates two files `peoplePayload.txt` and `people.txt` with the following content: -``` -Schema name is 'peoplePayload' and properties are: -- people -``` - -and -``` -Schema name is 'people' and properties are: -- id -``` - -> You can see an example of a file template that uses the Nunjucks render engine [here](https://github.com/asyncapi/template-for-generator-templates/tree/nunjucks/template/schemas). - ## Generating files with the React render engine -The above method of rendering **file templates** only works for the Nunjucks render engine. To use the React render engine, you need to follow a different approach. The React render engine allows for a more generic way to render multiple files by returning an array of `File` components in the rendering component. This can be particularly useful for complex templates or when you need to generate a large number of files with varying content. +The React render engine allows for a more generic way to render multiple files by returning an array of `File` components in the rendering component. This can be particularly useful for complex templates or when you need to generate a large number of files with varying content. ### Example 1: Rendering hardcoded files diff --git a/apps/generator/docs/generator-template-java.md b/apps/generator/docs/generator-template-java.md index aefe2ef383..776586bfea 100644 --- a/apps/generator/docs/generator-template-java.md +++ b/apps/generator/docs/generator-template-java.md @@ -61,7 +61,6 @@ Add the following code snippet to your package.json file: "version": "0.0.1", "description": "A template that generates a Java MQTT client using MQTT.", "generator": { - "renderer": "react", "apiVersion": "v1", "generator": ">=1.10.0 <2.0.0", "supportedProtocols": ["mqtt"] @@ -287,7 +286,6 @@ In **package.json** define a script property that you invoke by calling `npm run "version": "0.0.1", "description": "A template that generates a Java MQTT client using MQTT.", "generator": { - "renderer": "react", "apiVersion": "v1", "generator": ">=1.10.0 <2.0.0", "supportedProtocols": ["mqtt"], diff --git a/apps/generator/docs/generator-template.md b/apps/generator/docs/generator-template.md index 497c282a9d..f1eec45982 100644 --- a/apps/generator/docs/generator-template.md +++ b/apps/generator/docs/generator-template.md @@ -112,7 +112,6 @@ The **package.json** file is used to define the dependencies for your template. "version": "0.0.1", "description": "A template that generates a Python MQTT client using MQTT.", "generator": { - "renderer": "react", "apiVersion": "v1", "generator": ">=1.10.0 <2.0.0", "supportedProtocols": ["mqtt"] @@ -132,7 +131,6 @@ Here's what is contained in the code snippet above: - **version** - the current version of your template. - **description** - a description of what your template does. - **generator** - specify generator [specific configuration](https://www.asyncapi.com/docs/tools/generator/configuration-file). - - **renderer** - can either be [`react`](https://www.asyncapi.com/docs/tools/generator/react-render-engine) or [`nunjucks`](https://www.asyncapi.com/docs/tools/generator/nunjucks-render-engine). In this case the generator will pass your template to the react render engine to generate the output. - **apiVersion** - specifies which major version of the [Parser-API](https://github.com/asyncapi/parser-api) your template will use. - **generator** - a string representing the generator version-range your template is compatible with. - **supportedProtocols** - A list that specifies which protocols are supported by your template. @@ -328,7 +326,6 @@ In **package.json** you can have the scripts property that you invoke by calling "test": "npm run test:clean && npm run test:generate && npm run test:start" }, "generator": { - "renderer": "react", "apiVersion": "v1", "generator": ">=1.10.0 <2.0.0", "supportedProtocols": ["mqtt"] @@ -459,7 +456,7 @@ export default function ({ asyncapi, params }) { 4. Dynamically get the class name **TemperatureServiceClient** from the AsyncAPI document from the **info** object using the Parser API using the code: `asyncapi.info().title()` . It will return `Temperature Service`, then remove the spaces and add `Client` as a suffix. 5. There is no templating needed in the `__init__` function, there is only hardcoded information. -> If you're on the fence about which templating engine you should use in your template, check out the [React render engine](https://www.asyncapi.com/docs/tools/generator/react-render-engine) and [nunjucks render engine](https://www.asyncapi.com/docs/tools/generator/nunjucks-render-engine) documentation. +> If you're on the fence about which templating engine you should use in your template, check out the [React render engine](https://www.asyncapi.com/docs/tools/generator/react-render-engine) documentation. In the next section, you'll refactor your template to use React. #### 5c. Creating a reusable component diff --git a/apps/generator/docs/index.md b/apps/generator/docs/index.md index a80e025316..915e2084d1 100644 --- a/apps/generator/docs/index.md +++ b/apps/generator/docs/index.md @@ -24,8 +24,8 @@ The AsyncAPI generator is a tool that generates anything you want using the **[A 3. The **Parser** uses additional plugins such as the OpenAPI, RAML, or Avro schemas to validate custom schemas of message payloads defined in the **AsyncAPI Document**. 4. If the **Parser** determines that the original **AsyncAPI Document** is valid, it manipulates the document and returns a set of helper functions and properties and bundles them together into an **asyncapi** variable that is an instance of [**AsyncAPIDocument**](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#asyncapidocument). The **asyncapi** helper functions make it easier to access the contents of the AsyncAPI Document. 5. At this point, the **Generator** passes the **[asyncapi](generator/asyncapi-document#method-2-asyncapi-and-template)**, the **[originalAsyncAPI](generator/asyncapi-document#method-1-originalasyncapi-and-template)**, and the **params** which collectively make up the **[Template Context](generator/template-context)** to the **Render Engine**. -6. AsyncAPI has two **Render Engines**([react](generator/react-render-engine) and [nunjucks](generator/nunjucks-render-engine)). Depending on which one you've specified in your `package.json`, the **Generator** knows the right **Render Engine** to pass both the **Template Files** and the **Template Context**. -7. Once the **Render Engine** receives the **Template Files** and the **Template Context**, it injects all the dynamic values in your react or nunjucks based **Template Files** using the **Template Context**. As a result, the **Render Engine** generates **markdown**, **pdf**, **boilerplate code**, and **anything else** you specified to be generated as output. +6. AsyncAPI has a **Render Engine**([react](generator/react-render-engine)). The **Generator** passes both the **Template Files** and the **Template Context** to the **Render Engine**. +7. Once the **Render Engine** receives the **Template Files** and the **Template Context**, it injects all the dynamic values in your react based **Template Files** using the **Template Context**. As a result, the **Render Engine** generates **markdown**, **pdf**, **boilerplate code**, and **anything else** you specified to be generated as output. > You can generate anything you want using the generator as long as it can be defined in a **Template**. diff --git a/apps/generator/docs/migration-cli.md b/apps/generator/docs/migration-cli.md deleted file mode 100644 index c51c5f1d7f..0000000000 --- a/apps/generator/docs/migration-cli.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "Migrating from `ag` CLI to AsyncAPI CLI" -weight: 260 ---- - -This guide provides detailed instructions on how to transition from the old `ag` Generator CLI to the new AsyncAPI CLI. - -## Options Overview - -Here is a list of `ag` options and their equivalents in the AsyncAPI CLI: - -- **-d, --disable-hook [hooks...]** - - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate