Skip to content

Commit 867177e

Browse files
ianian
committed
add docs
1 parent ca99a76 commit 867177e

File tree

1 file changed

+324
-4
lines changed

1 file changed

+324
-4
lines changed

‎apps/public/content/docs/sdks/react.mdx‎

Lines changed: 324 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,325 @@
1-
---
2-
title: React
3-
---
41

5-
Use [script tag](/docs/sdks/script) or [Web SDK](/docs/sdks/web) for now. We'll add a dedicated react sdk soon.
2+
## About
3+
4+
The React SDK provides a clean, idiomatic way to use OpenPanel in React applications. Built on `@openpanel/sdk`, it follows the same architecture as the React Native SDK and includes:
5+
6+
- ✅ React Context API with `useOpenPanel()` hook
7+
- ✅ Full TypeScript support
8+
- ✅ SSR-safe (Next.js App Router & Pages Router)
9+
- ✅ Zero configuration with environment variables
10+
- ✅ Re-exports all SDK types and utilities
11+
12+
## Installation
13+
14+
<Steps>
15+
### Install dependencies
16+
17+
<Tabs items={['npm', 'pnpm', 'yarn']}>
18+
<Tab value="npm">
19+
```bash
20+
npm install @openpanel/react
21+
```
22+
</Tab>
23+
<Tab value="pnpm">
24+
```bash
25+
pnpm add @openpanel/react
26+
```
27+
</Tab>
28+
<Tab value="yarn">
29+
```bash
30+
yarn add @openpanel/react
31+
```
32+
</Tab>
33+
</Tabs>
34+
35+
This package requires React 18+ or React 19+.
36+
37+
### Initialize
38+
39+
Wrap your app with the `OpenPanelProvider` in your root component.
40+
41+
<Tabs items={['Next.js App Router', 'Next.js Pages Router', 'React']}>
42+
<Tab value="Next.js App Router">
43+
```tsx title="app/layout.tsx"
44+
import { OpenPanelProvider } from '@openpanel/react';
45+
46+
export default function RootLayout({
47+
children
48+
}: {
49+
children: React.ReactNode
50+
}) {
51+
return (
52+
<html lang="en">
53+
<body>
54+
<OpenPanelProvider
55+
clientId="your-client-id"
56+
trackScreenViews={true}
57+
>
58+
{children}
59+
</OpenPanelProvider>
60+
</body>
61+
</html>
62+
);
63+
}
64+
```
65+
</Tab>
66+
<Tab value="Next.js Pages Router">
67+
```tsx title="pages/_app.tsx"
68+
import { OpenPanelProvider } from '@openpanel/react';
69+
import type { AppProps } from 'next/app';
70+
71+
export default function App({ Component, pageProps }: AppProps) {
72+
return (
73+
<OpenPanelProvider
74+
clientId="your-client-id"
75+
trackScreenViews={true}
76+
>
77+
<Component {...pageProps} />
78+
</OpenPanelProvider>
79+
);
80+
}
81+
```
82+
</Tab>
83+
<Tab value="React">
84+
```tsx title="main.tsx"
85+
import { OpenPanelProvider } from '@openpanel/react';
86+
import { App } from './App';
87+
88+
export function Root() {
89+
return (
90+
<OpenPanelProvider
91+
clientId="your-client-id"
92+
trackScreenViews={true}
93+
>
94+
<App />
95+
</OpenPanelProvider>
96+
);
97+
}
98+
```
99+
</Tab>
100+
</Tabs>
101+
102+
### Using Environment Variables
103+
104+
The provider automatically reads from environment variables if no `clientId` prop is provided:
105+
106+
```tsx
107+
<OpenPanelProvider>
108+
{children}
109+
</OpenPanelProvider>
110+
```
111+
112+
Create a `.env.local` file (Next.js) or `.env` file:
113+
114+
```bash title=".env.local"
115+
NEXT_PUBLIC_OPENPANEL_CLIENT_ID=your_client_id_here
116+
```
117+
118+
The SDK checks for (in order):
119+
1. `NEXT_PUBLIC_OPENPANEL_CLIENT_ID` (Next.js client-side)
120+
2. `OPENPANEL_CLIENT_ID` (server-side or other environments)
121+
122+
#### Options
123+
124+
<CommonSdkConfig />
125+
<WebSdkConfig />
126+
127+
</Steps>
128+
129+
## Usage
130+
131+
### Client Components
132+
133+
Use the `useOpenPanel()` hook in any component wrapped by the provider:
134+
135+
```tsx title="components/subscribe-button.tsx"
136+
'use client';
137+
138+
import { useOpenPanel } from '@openpanel/react';
139+
140+
export function SubscribeButton() {
141+
const op = useOpenPanel();
142+
143+
const handleClick = () => {
144+
op?.track('button_clicked', {
145+
button_name: 'subscribe',
146+
page: 'homepage'
147+
});
148+
};
149+
150+
return <button onClick={handleClick}>Subscribe</button>;
151+
}
152+
```
153+
154+
### Tracking Events
155+
156+
Track custom events with properties:
157+
158+
```tsx
159+
const op = useOpenPanel();
160+
161+
op?.track('purchase', {
162+
product_id: 'prod-123',
163+
amount: 99.99,
164+
currency: 'USD'
165+
});
166+
```
167+
168+
### Identifying Users
169+
170+
Identify users to associate events with specific profiles:
171+
172+
```tsx
173+
const op = useOpenPanel();
174+
175+
op?.identify({
176+
profileId: 'user-123',
177+
email: '[email protected]',
178+
name: 'John Doe',
179+
properties: {
180+
plan: 'premium',
181+
company: 'Acme Inc'
182+
}
183+
});
184+
```
185+
186+
### Setting Global Properties
187+
188+
Set properties that will be sent with every event:
189+
190+
```tsx
191+
const op = useOpenPanel();
192+
193+
op?.setGlobalProperties({
194+
app_version: '1.0.2',
195+
environment: 'production'
196+
});
197+
```
198+
199+
### Incrementing Properties
200+
201+
Increment a numeric property on a user profile:
202+
203+
```tsx
204+
const op = useOpenPanel();
205+
206+
op?.increment({
207+
profileId: 'user-123',
208+
property: 'page_views',
209+
value: 1
210+
});
211+
```
212+
213+
### Decrementing Properties
214+
215+
Decrement a numeric property on a user profile:
216+
217+
```tsx
218+
const op = useOpenPanel();
219+
220+
op?.decrement({
221+
profileId: 'user-123',
222+
property: 'credits',
223+
value: 5
224+
});
225+
```
226+
227+
### Clearing User Data
228+
229+
Clear the current user's data (useful for logout):
230+
231+
```tsx
232+
const op = useOpenPanel();
233+
234+
op?.clear();
235+
```
236+
237+
## Server-Side Rendering (SSR)
238+
239+
The provider is SSR-safe and works seamlessly with Next.js:
240+
241+
- ✅ OpenPanel client only initializes in the browser
242+
- ✅ No hydration errors
243+
- ✅ Safe to use in Server Components (wrap client components that use the hook)
244+
245+
### Example with Server Component
246+
247+
```tsx title="app/page.tsx"
248+
import { AnalyticsButton } from './analytics-button';
249+
250+
export default function Page() {
251+
return (
252+
<div>
253+
<h1>My Page</h1>
254+
<AnalyticsButton />
255+
</div>
256+
);
257+
}
258+
```
259+
260+
```tsx title="app/analytics-button.tsx"
261+
'use client';
262+
263+
import { useOpenPanel } from '@openpanel/react';
264+
265+
export function AnalyticsButton() {
266+
const op = useOpenPanel();
267+
268+
return (
269+
<button onClick={() => op?.track('button_click')}>
270+
Click Me
271+
</button>
272+
);
273+
}
274+
```
275+
276+
## TypeScript Support
277+
278+
All types from `@openpanel/sdk` are re-exported for your convenience:
279+
280+
```tsx
281+
import {
282+
useOpenPanel,
283+
type OpenPanelOptions,
284+
type TrackProperties
285+
} from '@openpanel/react';
286+
287+
const properties: TrackProperties = {
288+
product_id: 'prod-123',
289+
amount: 99.99
290+
};
291+
292+
const op = useOpenPanel();
293+
op?.track('purchase', properties);
294+
```
295+
296+
## Advanced Usage
297+
298+
### Server-Side Tracking (Next.js)
299+
300+
For server-side event tracking in Next.js, use the JavaScript SDK directly:
301+
302+
```tsx title="utils/op.ts"
303+
import { OpenPanel } from '@openpanel/sdk';
304+
305+
export const opServer = new OpenPanel({
306+
clientId: 'your-client-id',
307+
clientSecret: 'your-client-secret',
308+
});
309+
```
310+
311+
Then use it in server components or API routes:
312+
313+
```tsx title="app/api/subscribe/route.ts"
314+
import { opServer } from '@/utils/op';
315+
316+
export async function POST() {
317+
await opServer.track('user_subscribed', {
318+
plan: 'premium'
319+
});
320+
321+
return Response.json({ success: true });
322+
}
323+
```
324+
325+
For more information on server-side tracking, refer to the [Next.js SDK](/docs/sdks/nextjs#server-side) documentation.

0 commit comments

Comments
 (0)