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.

import { Hub } from 'aws-amplify';

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);

})

**A note about onHubCapsule** In previous versions of Amplify capturing updates required you to implement an `onHubCapsule` handler function in your class and pass in `this` to the listen method. While still possible, this is no longer considered best practice and we have begun deprecating the method. Please define an explicit callback and pass it into the listen function (e.g. `Hub.listen('auth', this.myCallback)`) or use an anonymous function such as in the above example.

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, we encourage you to use it as it is required when using a `RegExp` filtering with `Hub.listen()`.

Hub provides a way to stop listening for messages with `Hub.remove(channel: string | RegExp, listener: callback)`. 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.

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

- api

- analytics

- interactions

- pubsub

- storage

- xr

{: .callout .callout--info}

Amplify's `Auth` category publishes in the `auth` channel when 'signIn', 'signUp', and 'signOut' events happen. You can listen and act upon those event notifications.

const logger = new Logger('My-Logger');

const listener = (data) => {

switch (data.payload.event) {

logger.error('user signed in'); //[ERROR] My-Logger - user signed in

logger.error('user signed up');

logger.error('user signed out');

logger.error('user sign in failed');

logger.error('the Auth module is configured');

Hub.listen('auth', listener);

The listener feature of Hub is a powerful way to perform filtering when you're unsure what the data across different channels will look like. Additionally it's also a nice realtime debugging feature. For instance, if you wanted to listen to all messages then you can just pass in a wildcard:

Hub.listen(/.*/, (data) => {

console.log('Listening for all messages: ', data.payload.data)

})

When using a "Capturing Group" (e.g. parenthesis grouping regular expressions) an array will be populated called `patternInfo` and returned as part of your callback:

Hub.listen(/user(.*)/, (data) => {

console.log('A USER event has been found matching the pattern: ', data.payload.message);

console.log('patternInfo:', data.patternInfo);

})

For example, this can be useful if you want to extract the text before and/or after a specific phrase:

Hub.listen(/user ([^ ]+) ([^ ]+) (.*)/, (data) => {

console.log('A USER event has been found matching the pattern: ', data.payload.message);

console.log('patternInfo:', data.patternInfo);

})

Hub can be used as part of a state management system such as [Redux](https://redux.js.org/) or [MobX](https://github.com/mobxjs/mobx) by updating the store when an event is seen by one or more listeners. You could also construct your own local store. For example, suppose you have the following in a React application's top level component:

const store = (() => {

const listeners = [];

const theStore = {

subscribe(listener) {

listeners.push(listener);

}

};

return new Proxy(theStore, {

set(_obj, _prop, _value) {

listeners.forEach(l => l());

return Reflect.set(...arguments);

}

});

})();

Hub.listen(/.*/, (data) => {

console.log('Listening for all messages: ', data.payload.data)

if (data.payload.message){

store['message-' + Math.floor(Math.random() * 100)] = data.payload.message

}

})

class App extends Component {

addItem = () => {

Hub.dispatch('MyGroup', {

data : { a: 1},

event: 'clicked',

message: 'A user clicked a button'

})

console.log(store);

}

render() {

console.log('store: ', store)

return (

<div className="App">

<button onClick={this.addItem}>Add item</button>

<DogAlerts store={store}/>

<DogStatus store={store}/>

</div>

);

}

}

This naive sample (which is for example purposes and not production ready) creates a `store` that is updated when events are received by `Hub.listen()` if there is a message present in the payload. We then create these messages with `Hub.dispatch()` upon a button click and pass the store down to two components called `<DogAlerts />` and `<DogStatus />`. The first is a very simple stateless component that renders the current store value from props:

const DogAlerts = (props) => {

return <pre>{JSON.stringify(props, null, 2)}</pre>

}

While this is nice functionality, when the button is clicked the component will not be updated. In order to do that you can use a class component (or React Hooks) and call `store.subscribe` as part of the `componentDidMount()` lifecycle method:

class DogStatus extends Component {

componentDidMount(){

this.props.store.subscribe(()=>{

this.forceUpdate();

})

}

render(){

return(<div>

<pre>Dog Status</pre>

<pre>{JSON.stringify(this.props, null, 2)}</pre>

</div>)

}

}

Now when the store is updated the `<DogStatus />` component re-renders on the screen.