Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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: 17 days 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 4 years ago)
Default Branch: master
Last Pushed: 2024-05-06T06:53:44.000Z (6 months ago)
Last Synced: 2024-05-21T18:07:37.648Z (6 months ago)
Topics: asyncapi, generator, get-global-node-release-workflows, get-global-releaserc, nodejs, template, websocket, websockets
Language: JavaScript
Homepage:
Size: 4.7 MB
Stars: 23
Watchers: 4
Forks: 27
Open Issues: 3
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS

Awesome Lists containing this project

README

        [![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}
💻 🤔

      
_{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!