Skip to main content

React

Integrate the General Wisdom Provider SDK in a React application with Vite and the useEffect hook pattern.

Prerequisites​

  • Node.js 20+
  • A Vite + React project (or create one below)
  • Your Application ID and API Key from the Provider Dashboard

Quick Setup​

npm create vite@latest my-gw-app -- --template react-ts
cd my-gw-app
npm install @mission_sciences/provider-sdk
npm run dev

Complete Example​

Entry Point​

src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

App Component​

src/App.tsx
import { useEffect } from 'react';
import { MarketplaceSDK } from '@mission_sciences/provider-sdk';

const APP_ID = 'YOUR_APP_ID';
const API_KEY = 'YOUR_API_KEY';

export default function App() {
  useEffect(() => {
    const sdk = new MarketplaceSDK({
      applicationId:            APP_ID,
      apiKey:                   API_KEY,
      environment:              'production',   // 'demo' | 'production'
      autoStart:                true,
      themeMode:                'auto',         // 'light' | 'dark' | 'auto'
      warningThresholdSeconds:  300,            // warn user 5 min before expiry
      enableHeartbeat:          false,          // keep-alive ping
      heartbeatIntervalSeconds: 30,
      debug:                    false,
    });

    sdk.initialize().catch(console.error);

    return () => {
      sdk.destroy();
    };
  }, []);

  return (
    <div>
      {/* Your application content */}
    </div>
  );
}
Replace placeholders

Swap YOUR_APP_ID and YOUR_API_KEY with the credentials from your Provider Dashboard.

Pattern Breakdown​

Why useEffect with an empty dependency array?​

The SDK manages a stateful connection to the General Wisdom platform. Using useEffect(fn, []) ensures:

  1. Single initialization — the SDK connects once when the component mounts.
  2. Cleanup on unmount — the returned function calls sdk.destroy() to release resources.
  3. No re-renders — the SDK handles its own UI; React does not need to re-render for session state changes.

StrictMode behavior​

In development, React StrictMode mounts components twice. This means useEffect fires, cleans up, then fires again. The SDK handles this gracefully — destroy() followed by a fresh initialize() is safe.

Configuration Options​

OptionTypeDefaultDescription
applicationIdstring—Your registered application ID
apiKeystring—Your API key
environment'demo' | 'production''production'Target environment
autoStartbooleantrueStart session automatically on init
themeMode'light' | 'dark' | 'auto''auto'UI theme preference
warningThresholdSecondsnumber300Seconds before expiry to show warning
enableHeartbeatbooleanfalseEnable keep-alive pings
heartbeatIntervalSecondsnumber30Interval between heartbeat pings
debugbooleanfalseEnable verbose console logging

Common Gotchas​

Forgetting the cleanup function​

If you omit return () => sdk.destroy(), the SDK connection persists after navigation or component unmount. This leaks memory and can cause duplicate sessions.

Storing the SDK instance in state​

Do not use useState for the SDK instance. The SDK is an imperative side-effect, not reactive UI state. Storing it in state triggers unnecessary re-renders and risks stale closures.

Environment variables​

In Vite, prefix env vars with VITE_:

.env
VITE_GW_APP_ID=app_abc123
VITE_GW_API_KEY=key_xyz789
const APP_ID = import.meta.env.VITE_GW_APP_ID;
const API_KEY = import.meta.env.VITE_GW_API_KEY;

Next Steps​