useSSE React Hook

Common errors

• TypeError: Cannot destructure property 'data' of 'undefined' as it is undefined.

  cause Attempting to access `data.isError` or similar properties on the returned data object when errors are now returned separately.
  fix Update your code to destructure the error object explicitly: `const [data, error] = useSSE(...);` and check `error` for details.

• Argument of type '{ data: string; }' is not assignable to parameter of type '() => Promise<any>'.

  cause Passing an initial state object as the first argument to `useSSE` in versions 2.0.0 or higher.
  fix Remove the initial state object. `useSSE` no longer accepts it: `useSSE(() => fetchData(), []);`

• Argument of type 'string' is not assignable to parameter of type '() => Promise<any>'.

  cause Passing the `key` string as the second argument to `useSSE` in versions 1.0.0 or higher.
  fix Remove the `key` parameter. The `useSSE` hook no longer requires it: `useSSE(() => fetchData(), []);`

Warnings

• breaking The `key` parameter for the `useSSE` hook was removed. Previously, it was the second argument. Calls to `useSSE` with a key will now fail or behave unexpectedly.
  Fix: Remove the `key` parameter from `useSSE` calls. The hook now infers keys or uses internal mechanisms for identification.
• breaking The `useSSE` hook no longer accepts an initial state object as its first argument. The initial data state is now always `null` by default.
  Fix: Remove the initial state object from the `useSSE` call. For example, change `useSSE({ data: 'initial' }, () => ...)` to `useSSE(() => ...)`.
• breaking Errors are now returned separately from the data as the second element in the tuple `[data, error]`. Previously, errors might have been embedded within the `data` object (e.g., `data.isError`).
  Fix: Adjust destructuring to `const [data, error] = useSSE(...)` and check the `error` variable directly for error details.
• gotcha Version 3.0.0-beta.0 introduces React 18 support. While it should be mostly compatible, users upgrading to React 18 should test thoroughly for any subtle behavioral changes or deprecated APIs, especially if relying on specific React lifecycle behaviors.
  Fix: Review your application's `useSSE` usage when upgrading to React 18. Ensure React 18's concurrent features do not interfere with expected data fetching and rehydration. Consult official React 18 migration guides.
• gotcha Security dependencies, including `lodash` and `elliptic`, have been updated across several versions (v2.0.1, v3.0.0-beta.0). While these are usually internal, it's a reminder to keep dependencies updated to avoid potential transitive vulnerabilities.
  Fix: Always keep `use-sse` and its dependencies updated to the latest stable versions to benefit from security patches. Regularly run `npm audit` or `yarn audit`.

Install

• npm install use-sse npm
• yarn add use-sse yarn
• pnpm add use-sse pnpm

Imports

• useSSE
  wrong:

  const useSSE = require('use-sse');

  correct:

  import { useSSE } from 'use-sse';

  The library is primarily designed for modern React environments and ES Modules. CommonJS `require` is not the intended or officially supported import method, especially with TypeScript.
• UseSSEHook

  import type { UseSSEHook } from 'use-sse';

  Importing types for use with TypeScript. The `useSSE` hook itself is typed, but explicit type imports can be useful for extending or documenting its usage.

Quickstart

This quickstart demonstrates how to use the `useSSE` hook to fetch data asynchronously, suitable for SSR scenarios. It shows how to pass a data-fetching function and a dependency array, and how to handle loading and error states.

import React from 'react';
import { useSSE } from 'use-sse';

// This function simulates an asynchronous data fetch that would typically happen on the server.
// In a real SSR setup, the return value would be serialized into the HTML and picked up by useSSE.
async function fetchData(itemId: string) {
  return new Promise<{ id: string; name: string }>(resolve => {
    setTimeout(() => {
      resolve({ id: itemId, name: `Item Data for ${itemId}` });
    }, 100); // Simulate network latency
  });
}

interface MyComponentProps {
  initialItemId: string;
}

function MyComponent({ initialItemId }: MyComponentProps) {
  // useSSE takes a data fetching function and a dependency array.
  // If running on the server, it executes `fetchData` and serializes the result.
  // On the client, it checks for serialized data before potentially re-running `fetchData`.
  const [data, error] = useSSE(() => fetchData(initialItemId), [initialItemId]);

  if (error) {
    return <div style={{ color: 'red' }}>Error loading data: {error.message}</div>;
  }

  if (!data) {
    // This will typically show on the client while hydrating if data isn't immediately available
    // or during initial client-side rendering if no SSR occurred.
    return <div>Loading...</div>;
  }

  return (
    <div>
      <h1>useSSE Example</h1>
      <p>Data loaded:</p>
      <pre>{JSON.stringify(data, null, 2)}</pre>
      <p>This data was likely pre-fetched during server-side rendering, reducing client-side load time.</p>
    </div>
  );
}

// Example usage within a React application
const App = () => <MyComponent initialItemId="product-abc" />;

export default App;