React Integration

The @pulse-js/react package provides a seamless integration with React, leveraging useSyncExternalStore for concurrent-mode safety.

Installation

npm install @pulse-js/react

usePulse Hook

This is the primary way to consume Pulse state.

With Sources

Returns the value and triggers re-render on change.

const count = source(0);

function Counter() {
  const value = usePulse(count);
  return <div>{value}</div>;
}

With Guards

Returns a GuardState object.

const isAdmin = guard(async () => { ... });

function AdminArea() {
  const { status, value, reason } = usePulse(isAdmin);

  if (status === 'pending') return <Spinner />;
  if (status === 'fail') return <Error msg={formatReason(reason)} />;

  return <Dashboard data={value} />;
}

formatReason Utility

The reason in a GuardState can be a string or a structured GuardReason object. To render it safely in your JSX components with full type safety, use the formatReason helper.

import { formatReason } from '@pulse-js/react';

function ErrorView({ reason }) {
  return <p>Error: {formatReason(reason)}</p>;
}

useGuard Hook

A specialized hook for guards that supports React Suspense.

import { useGuard } from '@pulse-js/react';

function ProtectedContent() {
  const { status, value } = useGuard(authGuard, { suspend: true });
  // If status is 'pending', this component will suspend
  return <div>{value}</div>;
}

PulseDevTools

You can manually mount the DevTools if you don’t want to use the auto-injector.

import { PulseDevTools } from '@pulse-js/react/devtools';

function App() {
  return (
    <>
       <Main />
       <PulseDevTools shortcut="Ctrl+J" />
    </>
  );
}