ward

Ward is a small JavaScript library providing tools to ease microfrontend development regardless of the chosen frameworks.

Concept

Ward provides seamless communication between existing frames by sending standardized messages coupled with dynamic plugin discovery mecanism.

API

Ward

| Function | Arguments | Description | | ---------- | ------------ | ----------- | | Features | | addService | id?: string | Creates a new service that will listen to incoming messages. | | loadPlugin | url?: string | ... | | reset | | Drop all services and plugins (should not be called). | | Inspection | | register | | ... | | unregister | | ... | | notify | | ... |

Service

Service objects are the basic communication entities in Ward. You can instanciate as many Service objects as needed in any layer of your application.

Service objects provide the ability to send a message that will be received by all other existing services in your execution environment, including the ones created in sub frames or parent frame.

| Function | Arguments | Description | | ------------- | --------- | ----------- | | addHandler | fn: (message: { type: string, payload: any }) => void | Add a handler to be called each time a message is received. | | removeHandler | fn: (message: { type: string, payload: any }) => void | Removes a previously added handler. | | sendMessage | message: { type: string, payload: any } | Sends a message to all other services. | | onMessage | message: { type: string, payload: any } | Sends a message to this service. | | terminate | _ | Prevent the service from receiving any further messages (can not be recycled) |

Usage

Installation

npm add @uncover/ward

Using Message Services

Example

Example #1: handlers

The following example creates a service that will log all messages sent to the Ward event bus.

import Ward from '@uncover/ward'

function messageLog(message) {
  console.log(`received message ${message.type}:`)
  console.log(JSON.stringify(message.payload))
}

// Create the service (with optionnal id)
const service = Ward.addService('my-service')

// Add a handler (will be called for each received message)
service.addHandler(messageLog)

// Remove a handler (stop calling it on message received)
service.removeHandler(messageLog)

// Terminate the service (stops receiving messages, service should be dropped)
service.terminate()

Example #2: sending messages

The following example creates a service and sends a message to the Ward event bus. The message will be dispatched to all other existing services.

import Ward from '@uncover/ward'

// Create the service (with optionnal id)
const service = Ward.addService('my-service')

// Send a message that will be received by all other services
service.sendMesage({
  type: 'my-message-type',
  payload: {
    data: 'myData',
    otherData: 'otherData'
  }
})

// Terminate the service (stops receiving messages, service should be dropped)
service.terminate()

Example #3: sending messages to handlers

Allthough considered a bad pattern, in some scenarios you might want to send a message to the handlers of your service. You can do it by simulating a message reception by the service.

import Ward from '@uncover/ward'

// Create the service (with optionnal id)
const service = Ward.addService('my-service')

// Send a message that will be received by all handlers of this service
service.onMesage({
  type: 'my-message-type',
  payload: {
    data: 'myData',
    otherData: 'otherData'
  }
})

// Terminate the service (stops receiving messages, service should be dropped)
service.terminate()