react-ebus

A lightweight and flexible event bus for React, designed to simplify inter-component communication using event-driven architecture.

---

🚀 Features

✅ Easy to integrate with any React project
✅ TypeScript support out of the box
✅ Supports both global and scoped events
✅ Handles dynamic event registration and cleanup
✅ Clean API for emitting and listening to events
✅ Fully compatible with React 19

📦 Installation

Install the package using npm:

npm install react-ebus

or with yarn:

yarn add react-ebus

---

🔥 Demo

---

🔨 Usage

1. Setup EventProvider

Wrap your app with the EventProvider to initialize the event bus:

import React from "react";
import { EventProvider } from "react-ebus";

const App = () => {
  return (
    <EventProvider
      registerEvents={{
        userlogin: "user:login",
        userlogout: "user:logout",
      }}
      allowAllEvents={false}
    >
      {/* If `allowAllEvents` is false, only registered events will be allowed */}
      <YourComponent />
    </EventProvider>
  );
};

export default App;

---

2. Emit Events using useEventEmitter

Use the useEventEmitter hook to emit events from any component.

import { useEventEmitter } from "react-ebus";

const YourComponent = () => {
  const { emit, eventList } = useEventEmitter();

  const handleLogin = () => {
    emit("user:login", { id: 1, name: "John Doe" }); // Emit directly by event name
  };

  const handleLoginWithRegisteredEvent = () => {
    emit(eventList.userlogin, { id: 1, name: "John Doe" }); // Emit using registered events to avoid typos
  };

  return (
    <div>
      <button onClick={handleLogin}>Login</button>
      <button onClick={handleLoginWithRegisteredEvent}>
        Login with Registered Event
      </button>
    </div>
  );
};

---

3. Listen to Events using useEventListener

Use the useEventListener hook to listen for events.

import { useEventListener } from "react-ebus";

const YourComponent = () => {
  const { unregister, unregisterAll } = useEventListener(
    {
      "user:login": (data) => {
        console.log("User logged in:", data);
      },
      "user:logout": () => {
        console.log("User logged out");
      },
    },
    { allowedAllEvents: false }
  );

  return (
    <div>
      <p>Listening for login and logout events...</p>
      <button onClick={() => unregister("user:login")}>
        Unregister Login Event
      </button>
      <button onClick={unregisterAll}>Unregister All Events</button>
    </div>
  );
};

---

🛠️ Props

EventProvider Props

Prop	Type	Required	Description
registerEvents	{[key:string]:string}	❌	List of allowed event names.
allowAllEvents	boolean	❌	If false, only registered events are allowed.

---

useEventEmitter Props

Prop	Type	Description
emit	(eventName: string, payload?: any) => void	Function to emit an event with an optional payload.
eventList	{[key: string]: string}	List of registered events.
isEventAllowed	(eventName: string) => boolean	Function to check if an event is allowed.

---

useEventListener Props

Prop	Type	Required	Description
eventListeners	Record<string, EventHandler>	✅	Object mapping event names to handler functions.
configuration	Partial<UseEventListenerConfig>	❌	Configuration object for allowing unregistered events.

---

EmitConfig Props (Optional)

Prop	Type	Description
allowedAllEvents	boolean	If true, allows emitting events even if unregistered.

---

🎯 Example

Combined Example with Emit and Listener:

import React from "react";
import {
  EventProvider,
  useEventEmitter,
  useEventListener,
} from "react-ebus";

const App = () => (
  <EventProvider
    registerEvents={{ customEvent: "custom:event" }}
    allowAllEvents={false}
  >
    <ComponentA />
    <ComponentB />
  </EventProvider>
);

const ComponentA = () => {
  const { emit } = useEventEmitter();

  return (
    <button onClick={() => emit("custom:event", { message: "Hello from A!" })}>
      Emit Event
    </button>
  );
};

const ComponentB = () => {
  useEventListener({
    "custom:event": (data) => {
      console.log("Event received:", data);
    },
  });

  return <div>Listening for events...</div>;
};

---

📜 TypeScript Support

Types are included out of the box:

export type EventHandler = (...args: any[]) => void;

export interface UseEventListenerConfig {
  allowedAllEvents?: boolean;
}

---

🚧 Development

Run TypeScript Check:

npm run type-check

Build the Package:

npm run build

Publish to npm:

npm publish --access public

---

✅ Best Practices

✔️ Always define and register events in EventProvider.
✔️ Clean up event listeners to avoid memory leaks.
✔️ Use TypeScript to ensure type safety.
✔️ Handle unknown or unregistered events gracefully.

---

⭐ Support the Project

If you like this project, consider giving it a ⭐ on GitHub!

---

👨‍💻 Author

Created by Saurabh

---

📄 License

This project is licensed under the MIT License.

---

🔥 Changes Made:

✅ Updated with useEventEmitter and useEventListener changes.
✅ Improved formatting for better readability.
✅ Added demo link and GitHub star button.
✅ Fixed consistency across examples.