@tiendanube/live-state 1.0.0-beta.8 → 1.0.0

package/README.md

@@ -88,6 +88,118 @@ That's it. The library handles rendering, tracking, and CTA behavior automatical
 
 ---
 
+## Caching behaviour (SWR)
+
+The lib uses [SWR](https://swr.vercel.app/) internally for data fetching, caching, and deduplication. Key implications:
+
+- **Single request per session** — all `useLiveState()` calls inside the same `LiveStateProvider` share one cached result. The backend is called once, regardless of how many pages or components use the hook.
+- **Cache key is fixed** — the cache key is the string `'live-state'`, not the fetcher URL. This means changing the `page` prop on `LiveStateRenderer` does **not** trigger a new request — the page is a frontend-only concern for tracking event names.
+- **Fetcher reference stability** — SWR does not re-fetch when the fetcher function reference changes, because the key is fixed. Even so, it is good practice to define the fetcher outside the component (or use `useCallback`/`useMemo`) to avoid unnecessary re-renders.
+- **Revalidation on reconnect** — the lib revalidates automatically when the browser reconnects to the network.
+- **No revalidation on focus** — focus-based revalidation is disabled to avoid extra requests when the user switches tabs.
+- **Manual refresh** — call `refresh()` from `useLiveState()` to force a re-fetch at any time.
+
+```tsx
+// ✅ Define fetcher outside the component — stable reference, no re-renders
+const fetcher: LiveStateFetcher = async () => { ... };
+
+function App() {
+  return <LiveStateProvider fetcher={fetcher}>...</LiveStateProvider>;
+}
+
+// ❌ Avoid defining fetcher inline — new reference on every render
+function App() {
+  return (
+    <LiveStateProvider fetcher={async () => { ... }}>...</LiveStateProvider>
+  );
+}
+```
+
+---
+
+## Testing utilities
+
+Import from `@tiendanube/live-state/testing` in your test files:
+
+```tsx
+import {
+  MockLiveStateProvider,
+  createMockLiveState,
+  mockUseLiveState,
+} from '@tiendanube/live-state/testing';
+
+// Render with controlled live state data
+render(
+  <MockLiveStateProvider liveState={createMockLiveState({ type: 'alert' })}>
+    <MyComponent />
+  </MockLiveStateProvider>
+);
+
+// Mock the hook directly in unit tests
+vi.mock('@tiendanube/live-state', async (importOriginal) => ({
+  ...(await importOriginal()),
+  useLiveState: () => mockUseLiveState({ liveState: createMockLiveState() }),
+}));
+```
+
+`MockLiveStateProvider` automatically sets `disabled={true}`, suppressing all analytics SDK calls in tests.
+
+---
+
+## Disabling analytics (dev / test / staging)
+
+Pass `disabled={true}` to `LiveStateProvider` to prevent the Amplitude and Clarity SDKs from being initialised. The prop value should come from your app's own environment variable — the library does not define or read any env var itself.
+
+```tsx
+// Vite
+<LiveStateProvider
+  fetcher={fetchLiveState}
+  disabled={import.meta.env.VITE_APP_ENV !== 'production'}
+>
+  ...
+</LiveStateProvider>
+
+// Create React App / Next.js
+<LiveStateProvider
+  fetcher={fetchLiveState}
+  disabled={process.env.NODE_ENV !== 'production'}
+>
+  ...
+</LiveStateProvider>
+```
+
+When `disabled` is `true`, `onEvent` callbacks still fire normally so you can observe tracking without hitting the real SDKs.
+
+---
+
+## Fetcher timeouts
+
+The library does not impose a timeout on the fetcher — if the endpoint hangs, `isLoading` will remain `true` indefinitely. Because live state notifications are non-critical UI, you should configure a timeout directly in your fetcher so that a slow backend never blocks the page.
+
+```tsx
+// Using axios
+const fetcher: LiveStateFetcher = async () => {
+  const { data } = await axios.get('/api/live-state', { timeout: 5000 });
+  return data ?? null;
+};
+
+// Using native fetch + AbortSignal
+const fetcher: LiveStateFetcher = async () => {
+  const controller = new AbortController();
+  const id = setTimeout(() => controller.abort(), 5000);
+  try {
+    const res = await fetch('/api/live-state', { signal: controller.signal });
+    return res.ok ? await res.json() : null;
+  } catch {
+    return null; // timeout or network error — fail silently
+  } finally {
+    clearTimeout(id);
+  }
+};
+```
+
+---
+
 ## Documentation
 
 - [Implementation Guide](./docs/IMPLEMENTATION_GUIDE.md) — full integration guide with usage patterns, API reference, and troubleshooting