React Event Hook

A library for emitting and listening to events within a React application.

This package was inspired by a Tweet from @pedronauck.


Installation

To install react-event-hook into your project, run the following command:

``bash
yarn add react-event-hook
`

Event Creation

Use the createEvent function to declare events. The only required argument is the event name. The function returns an object containing a listener and an emitter function, both named based on the provided event name.

`javascript
import { createEvent } from "react-event-hook";

const { usePingListener, emitPing } = createEvent("ping")();
const { usePongListener, emitPong } = createEvent("pong")();
`

$3

Enable the crossTab option to extend events to other tabs sharing the same origin. This feature allows local propagation of changes across multiple application instances.

`javascript
import { createEvent } from "react-event-hook";

const { useSignInListener, emitSignIn } = createEvent("sign-in")({
crossTab: true
});
`

$3

Since events are registered globally, ensure each event is created only once. Duplicate events sharing the same name may cause issues if their payloads differ. To avoid such problems, reuse the functions provided by createEvent throughout your application.

Event Listeners

Use the listener function returned by createEvent to listen for events. Listeners are implemented as custom React hooks.

`jsx
import { useMessageListener } from "./events";

const ListenerComponent = () => {
useMessageListener((message) => {
console.log("Received a message:", message);
});

return <>...;
};
`

Event Emitters

Emit events from anywhere in your application using the emitter function returned by createEvent.

`jsx
import { emitMessage } from "./events";

const EmitterComponent = () => (
emitMessage("hello")}>Send Message
);
`

Cross-tab event payloads are serialized using JSON.stringify. If a payload contains values that cannot be converted to JSON, an error will be thrown, and the event won't be delivered. Cross-tab payloads can contain arrays, objects, or primitive values (strings, numbers, booleans, null, undefined).

$3

Broadcast events exclusively to other tabs using the broadcast function. The emitting tab will not receive the event, but other tabs will. Ensure the crossTab option is enabled for your event.

`jsx
import { emitMessage } from "./events";

const EmitterComponent = () => (
emitMessage.broadcast("hello")}>Send Message
);
`

TypeScript

This library is written in TypeScript to ensure type safety. It requires TypeScript v4.1 or greater due to its use of Key Remapping and Template Literal Types.

$3

Specify event types using the following syntax:

`typescript
import { createEvent } from "react-event-hook";

interface Message {
subject: string;
body: string;
}

const { emitMessage } = createEvent("message")();

emitMessage({
subject: "greeting",
body: "hello"
});
`

Contributing

When contributing to this project, please first discuss the proposed changes through a GitHub issue.

Execute yarn test` and update the tests as necessary.

License

This project is licensed under the MIT License - see the LICENSE file for details.