[![AsyncAPI logo](./assets/github-repobanner-nodewstemp.png)](https://www.asyncapi.com) ![npm](https://img.shields.io/npm/v/@asyncapi/nodejs-ws-template?style=for-the-badge) ![npm](https://img.shields.io/npm/dt/@asyncapi/nodejs-ws-template?style=for-the-badge) - [Overview](#overview) - [Technical requirements](#technical-requirements) - [Specification requirements](#specification-requirements) - [Supported protocols](#supported-protocols) - [How to use the template](#how-to-use-the-template) * [CLI](#cli) - [Template configuration](#template-configuration) - [Custom hooks that you can disable](#custom-hooks-that-you-can-disable) - [Development](#development) - [Contributors](#contributors) ## Overview This template generates two resources related to WebSockets: - Server application with WebSocket endpoint based on [Express.js](https://expressjs.com/) - Client HTML file with simple scripts that give you a basic API to talk to the server Other files are for the setup of developer environment, like `.editorconfig` or `.eslint`. ## Technical requirements - 0.50.0 =< [Generator](https://github.com/asyncapi/generator/) < 2.0.0, - Generator specific [requirements](https://github.com/asyncapi/generator/#requirements) ## Specification requirements This is a very early version of the template and not all specification features are supported: Property name | Reason | Fallback | Default ---|---|---|--- `servers.*.url` | Template doesn't support variables in the server url. | - | - `bindings` | Template doesn't use [websockets](https://github.com/asyncapi/bindings/tree/master/websockets) bindings.| - | - `operationId` | Operation ID must be set for every operation to generate proper functions as there is no fallback in place | - | - ## Supported protocols [WebSocket](https://en.wikipedia.org/wiki/WebSocket) ## How to use the template This template must be used with the AsyncAPI Generator. You can find all available options [here](https://github.com/asyncapi/generator/). ### CLI ```bash # Install the AsyncAPI Generator npm install -g @asyncapi/generator # Run generation ag https://raw.githubusercontent.com/asyncapi/generator/v1.4.0/test/docs/ws.yml @asyncapi/nodejs-ws-template -o output -p server=localhost ## ## Start the server ## # Go to the generated server cd output # Build generated application npm i # Start server npm start ## ## Start the client ## # From another terminal tab open generated HTML in browser open output/index.html # Open developers console and follow instructions from there # Connect with server listen('/echo') # Send example message send({ greet: 'Hello from client' }) # You should see the sent message in the logs of the previously started server ``` ## Template configuration You can configure this template by passing different parameters in the Generator CLI: `-p PARAM1_NAME=PARAM1_VALUE -p PARAM2_NAME=PARAM2_VALUE` | Name | Description | Required | Default | Allowed Values | Example |---|---|---|---|---|---| |server|The server you want to use in the code.|Yes| - | Name of the server from the list of servers under Servers object | `localhost`| ## Custom hooks that you can disable The functionality of this template is extended with different hooks that you can disable like this in the Generator CLI: `-d HOOK_TYPE1=HOOK_NAME1,HOOK_NAME2 -d HOOK_TYPE2` Type | Name | Description ---|---|--- generate:after | createAsyncapiFile | It creates AsyncAPI file with content of the spec file passed to the generator ## Development The most straightforward command to use this template is: ```bash ag https://raw.githubusercontent.com/asyncapi/generator/v1.4.0/test/docs/ws.yml @asyncapi/nodejs-ws-template -o output -p server=localhost ``` For local development, you need different variations of this command. First of all, you need to know about three important CLI flags: - `--debug` enables the debug mode in Nunjucks engine what makes filters debugging simpler. - `--watch-template` enables a watcher of changes that you make in the template. It regenerates your template whenever it detects a change. - `--install` enforces reinstallation of the template. There are two ways you can work on template development: - Use global Generator and template from your local sources: ```bash # assumption is that you run this command from the root of your template ag https://raw.githubusercontent.com/asyncapi/generator/v1.4.0/test/docs/ws.yml ./ -o output ``` - 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: ```bash # assumption is that you run this command from the root of your template # assumption is that generator sources are cloned on the same level as the template ../generator/cli.js https://raw.githubusercontent.com/asyncapi/generator/v1.4.0/test/docs/ws.yml ./ -o output ``` ## Contributors Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Fran MΓ©ndez
Fran MΓ©ndez
πŸ’» πŸ€”		 Lukasz Gornicki
Lukasz Gornicki
πŸš‡ πŸ’» πŸ‘€ 🚧 πŸ“– πŸ“		 Aayush Kumar Sahu
Aayush Kumar Sahu
πŸ›‘οΈ		 Katrina Knight
Katrina Knight
πŸš‡		 Olivier Lechevalier
Olivier Lechevalier
πŸ’»		 Krishna Kumar S
Krishna Kumar S
⚠️		 Ivan Kahl
Ivan Kahl
πŸ’» ⚠️
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!