• Overview
• Technical requirements
• Specification requirements
• Supported protocols
• How to use the template
  • CLI
• Template configuration
• Custom hooks that you can disable
• Development
• Contributors

Overview

This template generates two resources related to WebSockets:

• Server application with WebSocket endpoint based on Express.js
• 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 < 2.0.0,
• Generator specific 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 bindings.| - | - operationId | Operation ID must be set for every operation to generate proper functions as there is no fallback in place | - | -

Supported protocols

WebSocket

How to use the template

This template must be used with the AsyncAPI Generator. You can find all available options here.

CLI

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

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:

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

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

This project follows the all-contributors specification. Contributions of any kind welcome!