https://github.com/asyncapi/nodejs-ws-template
Node.js WebSockets template for the AsyncAPI Generator. It showcases how from a single AsyncAPI document you can generate a server and a client at the same time.
https://github.com/asyncapi/nodejs-ws-template
asyncapi generator get-global-node-release-workflows get-global-releaserc nodejs template websocket websockets
Last synced: 7 months ago
JSON representation
Node.js WebSockets template for the AsyncAPI Generator. It showcases how from a single AsyncAPI document you can generate a server and a client at the same time.
- Host: GitHub
- URL: https://github.com/asyncapi/nodejs-ws-template
- Owner: asyncapi
- Created: 2020-03-20T18:13:45.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-10-14T17:07:41.000Z (about 1 year ago)
- Last Synced: 2024-10-29T22:38:04.594Z (about 1 year ago)
- Topics: asyncapi, generator, get-global-node-release-workflows, get-global-releaserc, nodejs, template, websocket, websockets
- Language: JavaScript
- Homepage:
- Size: 4.98 MB
- Stars: 25
- Watchers: 4
- Forks: 29
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
[](https://www.asyncapi.com)
 
- [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
💻 🤔
Lukasz Gornicki
🚇 💻 👀 🚧 📖 📝
Aayush Kumar Sahu
🛡️
Katrina Knight
🚇
Olivier Lechevalier
💻
Krishna Kumar S
⚠️
Ivan Kahl
💻 ⚠️
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!