@harelpls/use-pusher

Easy as React hooks that integrate with the pusher-js library.

• Install
• Hooks
• Usage
• useChannel
• usePresenceChannel
• useEvent
• useTrigger
• usePusher
• Trigger Server
• useClientTrigger
• Typescript
• Testing
• React Native
• Contributing
• License

API Reference/Docs

Install

1yarn add @harelpls/use-pusher

Hooks

• useChannel
• usePresenceChannel
• useEvent
• useTrigger
• useClientTrigger
• usePusher

Usage

You must wrap your app with a PusherProvider and pass it config props for pusher-js initialisation.

1import React from "react";
2import { PusherProvider } from "@harelpls/use-pusher";
3
4const config = {
5  // required config props
6  clientKey: "client-key",
7  cluster: "ap4",
8
9  // optional if you'd like to trigger events. BYO endpoint.
10  // see "Trigger Server" below for more info
11  triggerEndpoint: "/pusher/trigger",
12
13  // required for private/presence channels
14  // also sends auth headers to trigger endpoint
15  authEndpoint: "/pusher/auth",
16  auth: {
17    headers: { Authorization: "Bearer token" },
18  },
19};
20
21// Wrap app in provider
22const App = () => {
23  <PusherProvider {...config}>
24    <Example />
25  </PusherProvider>;
26};

useChannel

Use this hook to subscribe to a channel.

1// returns channel instance.
2const channel = useChannel("channel-name");

usePresenceChannel

Augments a regular channel with member functionality.

1const Example = () => {
2  const { members, myID } = usePresenceChannel('presence-awesome');
3
4  return (
5    <ul>
6      {Object.entries(members)
7        // filter self from members
8        .filter(([id]) => id !== myID)
9        // map them to a list
10        .map(([id, info]) => (
11          <li key={id}>{info.name}</li>
12        ))
13      }
14    </ul>
15  )
16}

useEvent

Bind to events on a channel with a callback.

1const Example = () => {
2  const [message, setMessages] = useState();
3  const channel = useChannel("channel-name");
4  useEvent(channel, "message", ({ data }) =>
5    setMessages((messages) => [...messages, data])
6  );
7};

Note: This will bind and unbind to the event on each render. You may want to memoise your callback with useCallback before passing it in if you notice performance issues.

useTrigger

A helper function to create a server triggered event. BYO server (See Trigger Server below). Pass in triggerEndpoint prop to <PusherProvider />. Any auth headers from config.auth.headers automatically get passed to the fetch call.

1import { useTrigger } from '@harelpls/use-pusher';
2
3const Example = () => {.
4  const trigger = useTrigger("channel-name");
5  const handleClick = () =>
6    trigger("event-name", "hello");
7
8  return (
9    <button onClick={handleClick}>Say Hello</button>
10  )
11}

usePusher

Get access to the Pusher instance to do other things.

1import { usePusher } from "@harelpls/use-pusher";
2
3const Example = () => {
4  const { client } = usePusher();
5  client.log("Look ma, logs!");
6
7  return null;
8};

Trigger Server

In order to trigger an event, you'll have to create a simple lambda (or an express server if that's your thing). Below is a short lambda that can handle triggered events from useTrigger.

1import Pusher from "pusher";
2
3const pusher = new Pusher({
4  appId: "app-id",
5  key: "client-key",
6  secret: "mad-secret",
7  cluster: "ap4",
8});
9
10export async function handler(event) {
11  const { channelName, eventName, data } = JSON.parse(event.body);
12  pusher.trigger(channelName, eventName, data);
13  return { statusCode: 200 };
14}

useClientTrigger

I don't want a server though

I hear ya. If you're feeling audacious, you can use client events to push directly from the client:

1import { useChannel, useClientTrigger } from "@harelpls/use-pusher";
2
3const Example = () => {
4  const channel = useChannel("presence-ca");
5  const trigger = useClientTrigger(channel);
6  const handleClientEvent = () => {
7    trigger("Pew pew");
8  };
9
10  return <button onClick={handleClientEvent}>Fire</button>;
11};

Typescript

This project was built using typescript, so types are built-in. Yeeeew!

Testing

I've teamed up with @nikolalsvk on pusher-js-mock to bring y'all a great pusher mock.

Testing emitted events with jest can be achieved using jest.mock and @testing-library/react (or enzyme, though your tests should reflect what the user should see NOT how the component handles events internally):

1// Example.tsx
2import React from "react";
3import { useChannel, useEvent } from "@harelpls/use-pusher";
4
5const Example = () => {
6  const [title, setTitle] = useState();
7  const channel = useChannel("my-channel");
8  useEvent(channel, "title", ({ data }) => setTitle(data));
9
10  return <span>{title}</span>;
11};
12
13// Example.test.tsx
14import { render, act } from "@testing-library/react";
15import { PusherMock, PusherChannelMock } from "pusher-js-mock";
16
17// mock out the result of the useChannel hook
18const mockChannel = new PusherChannelMock();
19jest.mock("@harelpls/use-pusher", () => ({
20  ...require.requireActual("@harelpls/use-pusher"),
21  useChannel: () => mockChannel,
22}));
23
24test("should show a title when it receives a title event", async () => {
25  // mock the client
26  const client = new PusherMock("client-key", { cluster: "ap4" });
27
28  // render component and provider with a mocked context value
29  const { findByText } = render(
30    <PusherProvider clientKey="client-key" cluster="ap4" value={{ client }}>
31      <Example />
32    </PusherProvider>
33  );
34
35  // emit an event on the mocked channel
36  act(() => mockChannel.emit("title", { data: "Hello world" }));
37
38  // assert expectations
39  expect(await findByText("Hello world")).toBeInTheDocument();
40});

Check out the example tests for testing presence channels.

React Native

This package comes with React Native support. Import your PusherProvider from @harelpls/use-pusher/react-native instead of the default @harelpls/use-pusher. All exports are re-exported from there.

Ensure you add the netinfo package to your project too: @react-native-community/netinfo.

1import { PusherProvider, useChannel } from "@harelpls/use-pusher/react-native";

Contributing

1. Clone the repository and run yarn && yarn test:watch
2. Get coding!

Please write tests (100% jest coverage) and types.

License

MIT © @mayteio

---

This hook is created using create-react-hook.