Hub

Amplify has a local eventing system called Hub. It is a lightweight implementation of Publisher-Subscriber pattern, and is used to share data between modules and components in your app. Amplify uses Hub for different categories to communicate with one another when specific events occur, such as authentication events like a user sign-in or notification of a file download.

Installation

import { Hub } from 'aws-amplify/utils';

Working with the API

Channels

A channel is a logical group name that you use to organize messages and listen on. These are strings and completely up to you as the developer to define for dispatching or listening. However, while you can dispatch to any channel, Amplify protects certain channels and will flag a warning as sending unexpected payloads could have undesirable side effects (such as impacting authentication flows). The protected channels are currently:

• core
• auth
• analytics
• storage

Listening for messages

listen(channel: string, callback: HubCallback): StopListenerCallback is used to listen for messages that have been dispatched. You must provide either a named channel or a regular expression, along with a callback. In the case of a regular expression only dispatches which contain a message in their payload will be matched against your pattern. You can add multiple listeners to your application for different channels or patterns to listen for, or trap generic events and perform your own filtering.

import { Hub } from 'aws-amplify/utils';

class MyClass {
  constructor() {
    Hub.listen('auth', (data) => {
      const { payload } = data;
      this.onAuthEvent(payload);
      console.log(
        'A new auth event has happened: ',
        data.payload.data.username + ' has ' + data.payload.event
      );
    });
  }

  onAuthEvent(payload) {
    // ... your implementation
  }
}

Sending messages

Sending events to different channels is done with the dispatch function:

Hub.dispatch('DogsChannel', {
  event: 'buttonClick',
  data: { color: 'blue' },
  message: ''
});

setTimeout(() => {
  Hub.dispatch('CatsChannel', {
    event: 'drinkMilk',
    data: {
      breed: 'Persian',
      age: 5
    },
    message: `The cat ${cat.name} has finished her milk`
  });
}, 5000);

Hub.dispatch(channel: string, payload: HubPayload) can be used to dispatch a HubPayload to a channel. The channel is a logical grouping for your organization while the HubPayload is a type defined as:

export type HubPayload = {
  event: string,
  data?: any,
  message?: string
};

The event field is recommended to be a small string without spaces such as signIn or hang_up as it's useful for checking payload groupings. The data field is a freeform structure which many times is used for larger JSON objects or custom data types. Finally while message is optional.

Stop Listening

Hub provides a way to stop listening for messages with calling the result of the .listen function. This may be useful if you no longer need to receive messages in your application flow, as well as to avoid any memory leaks on low powered devices when you are sending large amounts of data through Hub on multiple channels.

To stop listening to a certain event, you need to wrap the listener function to a variable and call it once you no longer need it:

/* start listening for messages */
const hubListenerCancel = Hub.listen('auth', (data) => {
  console.log('Listening for all messages: ', data.payload.data);
});

/* later */
hubListenerCancel(); // stop listening for messages