{"id":14155495,"url":"https://github.com/asyncapi/nodejs-template","last_synced_at":"2025-06-17T07:40:33.860Z","repository":{"id":37907256,"uuid":"248820246","full_name":"asyncapi/nodejs-template","owner":"asyncapi","description":"This template generates a server using your AsyncAPI document. It supports multiple different protocols, like Kafka or MQTT.  It is designed in the way that generated code is a library and with it's API you can start the server, send messages or register a middleware for listening incoming messages. Runtime message validation included.","archived":false,"fork":false,"pushed_at":"2024-11-19T15:45:26.000Z","size":5254,"stargazers_count":40,"open_issues_count":5,"forks_count":30,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-11-30T23:04:41.009Z","etag":null,"topics":["asyncapi","generator","get-global-node-release-workflows","get-global-releaserc","hacktoberfest","nodejs","template"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asyncapi.png","metadata":{"funding":{"github":"asyncapi","patreon":null,"open_collective":"asyncapi","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null},"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-20T17:59:56.000Z","updated_at":"2024-11-19T15:45:45.000Z","dependencies_parsed_at":"2023-12-15T22:06:29.790Z","dependency_job_id":"d22c4d95-5de9-4cbd-8378-805f6fcddef1","html_url":"https://github.com/asyncapi/nodejs-template","commit_stats":{"total_commits":229,"total_committers":18,"mean_commits":"12.722222222222221","dds":0.3580786026200873,"last_synced_commit":"c9c04b7403dc336e57e083389404a30dfe3f9711"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asyncapi%2Fnodejs-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asyncapi%2Fnodejs-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asyncapi%2Fnodejs-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asyncapi%2Fnodejs-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asyncapi","download_url":"https://codeload.github.com/asyncapi/nodejs-template/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228792713,"owners_count":17973052,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncapi","generator","get-global-node-release-workflows","get-global-releaserc","hacktoberfest","nodejs","template"],"created_at":"2024-08-17T08:03:29.665Z","updated_at":"2024-12-09T02:31:23.318Z","avatar_url":"https://github.com/asyncapi.png","language":"JavaScript","funding_links":["https://github.com/sponsors/asyncapi","https://opencollective.com/asyncapi"],"categories":["nodejs"],"sub_categories":[],"readme":"[![AsyncAPI logo](./assets/github-repobanner-nodetemp.png)](https://www.asyncapi.com)  \n\\\n![npm](https://img.shields.io/npm/v/@asyncapi/nodejs-template?style=for-the-badge) ![npm](https://img.shields.io/npm/dt/@asyncapi/nodejs-template?style=for-the-badge)\n\n\u003c!-- toc is generated with GitHub Actions do not remove toc markers --\u003e\n\n\u003c!-- toc --\u003e\n\n- [Overview](#overview)\n- [Technical requirements](#technical-requirements)\n- [Specification requirements](#specification-requirements)\n- [Supported protocols](#supported-protocols)\n- [How to use the template](#how-to-use-the-template)\n  * [CLI](#cli)\n  * [Adding custom code / handlers](#adding-custom-code--handlers)\n- [Template configuration](#template-configuration)\n- [Development](#development)\n- [Contributors](#contributors)\n\n\u003c!-- tocstop --\u003e\n\n## Overview\n\nThis template generates a Node.js application with any of the [supported protocols](#supported-protocols) endpoint, based on [Hermesjs](https://github.com/hitchhq/hermes).\n\nOther files are for the setup of developer environment, like `.editorconfig` or `.eslint`.\n\n## Technical requirements\n\n- 0.50.0 =\u003c [Generator](https://github.com/asyncapi/generator/) \u003c 2.0.0,\n- Generator specific [requirements](https://github.com/asyncapi/generator/#requirements)\n\n\n## Specification requirements\n\nProperty name | Reason | Fallback | Default\n---|---|---|---\n`operationId` | Operation ID must be set for every operation to generate proper functions as there is no fallback in place | - | -\n\n\n## Supported protocols\n\n* [AMQP](https://en.wikipedia.org/wiki/Advanced_Message_Queuing_Protocol)\n* [MQTT and MQTTS](https://en.wikipedia.org/wiki/MQTT)\n* [Kafka](https://en.wikipedia.org/wiki/Apache_Kafka)\n* [WebSocket](https://en.wikipedia.org/wiki/WebSocket)\n\n## How to use the template\n\nThis template must be used with the AsyncAPI Generator. You can find all available options [here](https://github.com/asyncapi/generator/).\n\nIn case you use X509 security and need to provide certificates, either place them in the root of the generated server with the following names: `ca.pem`, `service.cert`, `service.key`. You can provide a custom directory where cert files are located using `certFilesDir` parameter like `-p certFilesDir=../not/in/my/app/dir`.\n\nSince you can have multiple different security schemes, to use the one of X509 type, you need to pass the name of the scheme like this: `-p securityScheme=SCHEME_NAME`.\n\n\u003e You can find a complete tutorial on AsyncAPI Generator using this template [here](https://www.asyncapi.com/docs/tutorials/streetlights). \n\n### CLI\n\n```bash\n# Install the AsyncAPI CLI\n# Follow https://www.asyncapi.com/docs/tools/generator/installation-guide for more installation options\n$ npm install -g @asyncapi/cli\n\n# Run generation from the root of the template to use tes MQTT example\n# To use the template\n$ asyncapi generate fromTemplate test/mocks/mqtt/asyncapi-v3.yml @asyncapi/nodejs-template -o test/output -p server=production\n\n# OR\n\n# To test your local changes provided inside template\n$ asyncapi generate fromTemplate test/mocks/mqtt/asyncapi-v3.yml ./ -o test/output -p server=production\n\n##\n## Install dependencies of generated library\n##\n\n# Go to the generated server\n$ cd test/output\n\n# Build generated application\n$ npm i\n\n##\n## Start an example script that uses generated library\n##\n\n# Go back to root\n$ cd ../..\n\n# Start the script\n# It is located in test/example/script.js\n$ npm run test:example\n\n##\n## Install MQTT client locally to start simulating some traffic on the broker, to test if sample code works\n##\n\n# for testing your server you can use mqtt client. Open a new terminal and install it using:\n$ npm install mqtt -g\n\n#You should see the sent message in the logs of the started example.\n\n#publish a valid message\n$ mqtt pub -t 'smartylighting/streetlights/1/0/event/123/lighting/measured' -h 'test.mosquitto.org' -m '{\"id\": 1, \"lumens\": 3, \"sentAt\": \"2017-06-07T12:34:32.000Z\"}'\n\n#you can also restart the example app that on startup produces some messages as well. Before you do it, subscribe with MQTT client to selected topic, to see actuall messages comming in from the broker\n$ mqtt sub -t 'smartylighting/streetlights/1/0/action/1/turn/on' -h 'test.mosquitto.org'\n```\n\n### Adding custom code / handlers\n\nIt's highly recommended to treat the generated template as a library or API for initializing the server and integrating user-written handlers. Instead of directly modifying the template, leveraging it in this manner ensures that its regenerative capability is preserved. Any modifications made directly to the template would be overwritten upon regeneration.\n\nConsider a scenario where you intend to introduce a new channel or section to the AsyncAPI file, followed by a template regeneration. In this case, any modifications applied within the generated code would be overwritten.\n\nTo avoid this, user code remains external to the generated code, functioning as an independent entity that consumes the generated code as a library. By adopting this approach, the user code remains unaffected during template regenerations.\n\nFacilitating this separation involves creating handlers and associating them with their respective routes. These handlers can then be seamlessly integrated into the template's workflow by importing the appropriate methods to register the handlers. In doing so, the template's `client.register\u003coperationId\u003eMiddleware` method becomes the bridge between the user-written handlers and the generated code. This can be used to register middlewares for specific methods on specific channels.\n\nLook closely into [example script](test/example/script.js) that works with library generated using [this MQTT based AsyncAPI document](test/mocks/mqtt/asyncapi.yml). Look at available handlers API for reading incomming messages and processing outgoing messages. Learn how to start generated server with `init()` and also learn how to send messages, if needed.\n\n## Template configuration\n\nYou can configure this template by passing different parameters in the Generator CLI: `-p PARAM1_NAME=PARAM1_VALUE -p PARAM2_NAME=PARAM2_VALUE`\n\n|Name|Description|Required|Example|\n|---|---|---|---|\n|server|The server you want to use in the code.|Yes|`production`|\n|securityScheme|Name of the security scheme. Only scheme with X509 and Kafka protocol is supported for now.|No|'mySchemeName'|\n|certFilesDir|Directory where application certificates are located. This parameter is needed when you use X509 security scheme and your cert files are not located in the root of your application.|No|`../not/in/my/app/dir`|\n\n## Development\n\nThe most straightforward command to use this template is:\n```bash\n$ ag https://bit.ly/asyncapi @asyncapi/nodejs-template -o output -p server=production\n```\n\n**Setup locally**\n\n```bash\n# Run following commands in terminal:\n$ git clone https://github.com/{username}/nodejs-template\n$ cd nodejs-template\n$ npm install\n$ ag https://bit.ly/asyncapi ./ -o output -p server=production\n```\n\nFor local development, you need different variations of this command. First of all, you need to know about three important CLI flags:\n- `--debug` enables the debug mode in React rendering engine what makes filters debugging simpler.\n- `--watch-template` enables a watcher of changes that you make in the template. It regenerates your template whenever it detects a change.\n- `--install` enforces reinstallation of the template.\n\n\nThere are two ways you can work on template development:\n- Use global Generator and template from your local sources:\n  ```bash\n  # assumption is that you run this command from the root of your template\n  $ ag https://bit.ly/asyncapi ./ -o output -p server=production\n  ```\n- Use Generator from sources and template also from local sources. This approach enables more debugging options with awesome `console.log` in the Generator sources or even the Parser located in `node_modules` of the Generator:\n  ```bash\n  # assumption is that you run this command from the root of your template\n  # assumption is that generator sources are cloned on the same level as the template\n  $ ../generator/cli.js https://bit.ly/asyncapi ./ -o output -p server=production\n  ```\n\n\n## Contributors\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://www.fmvilas.com/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/242119?v=4?s=100\" width=\"100px;\" alt=\"Fran Méndez\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eFran Méndez\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/asyncapi/nodejs-template/commits?author=fmvilas\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"#ideas-fmvilas\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://dev.to/derberg\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/6995927?v=4?s=100\" width=\"100px;\" alt=\"Lukasz Gornicki\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eLukasz Gornicki\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#infra-derberg\" title=\"Infrastructure (Hosting, Build-Tools, etc)\"\u003e🚇\u003c/a\u003e \u003ca href=\"https://github.com/asyncapi/nodejs-template/commits?author=derberg\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/KhudaDad414\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/32505158?v=4?s=100\" width=\"100px;\" alt=\"Khuda Dad Nomani\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eKhuda Dad Nomani\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/asyncapi/nodejs-template/commits?author=KhudaDad414\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"https://github.com/asyncapi/nodejs-template/commits?author=KhudaDad414\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://samridhi-98.github.io/Portfolio\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/54466041?v=4?s=100\" width=\"100px;\" alt=\"Samriddhi\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eSamriddhi\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/asyncapi/nodejs-template/commits?author=Samridhi-98\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/asyncapi/nodejs-template/commits?author=Samridhi-98\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/wandertaker\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/23746861?v=4?s=100\" width=\"100px;\" alt=\"Julius Jann\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eJulius Jann\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/asyncapi/nodejs-template/commits?author=wandertaker\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/asyncapi/nodejs-template/commits?author=wandertaker\" title=\"Tests\"\u003e⚠️\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://rishikaushik.com\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/52498617?v=4?s=100\" width=\"100px;\" alt=\"Rishi\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eRishi\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/asyncapi/nodejs-template/commits?author=kaushik-rishi\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/asyncapi/nodejs-template/commits?author=kaushik-rishi\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"https://github.com/asyncapi/nodejs-template/commits?author=kaushik-rishi\" title=\"Tests\"\u003e⚠️\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasyncapi%2Fnodejs-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasyncapi%2Fnodejs-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasyncapi%2Fnodejs-template/lists"}