1# RealtimeKit Patterns
2 
3## UI Kit (Minimal Code)
4 
5```tsx
6// React
7import { RtkMeeting } from '@cloudflare/realtimekit-react-ui';
8<RtkMeeting authToken="<token>" onLeave={() => console.log('Left')} />
9 
10// Angular
11@Component({ template: `<rtk-meeting [authToken]="authToken" (rtkLeave)="onLeave($event)"></rtk-meeting>` })
12export class AppComponent { authToken = '<token>'; onLeave(event: unknown) {} }
13 
14// HTML/Web Components
15<script type="module" src="https://cdn.jsdelivr.net/npm/@cloudflare/realtimekit-ui/dist/realtimekit-ui/realtimekit-ui.esm.js"></script>
16<rtk-meeting id="meeting"></rtk-meeting>
17<script>document.getElementById('meeting').authToken = '<token>';</script>
18```
19 
20## UI Components
21 
22RealtimeKit provides 133+ pre-built Stencil.js Web Components with framework wrappers:
23 
24### Layout Components
25- `<RtkMeeting>` - Full meeting UI (all-in-one)
26- `<RtkHeader>`, `<RtkStage>`, `<RtkControlbar>` - Layout sections
27- `<RtkSidebar>` - Chat/participants sidebar
28- `<RtkGrid>` - Adaptive video grid
29 
30### Control Components  
31- `<RtkMicToggle>`, `<RtkCameraToggle>` - Media controls
32- `<RtkScreenShareToggle>` - Screen sharing
33- `<RtkLeaveButton>` - Leave meeting
34- `<RtkSettingsModal>` - Device settings
35 
36### Grid Variants
37- `<RtkSpotlightGrid>` - Active speaker focus
38- `<RtkAudioGrid>` - Audio-only mode
39- `<RtkPaginatedGrid>` - Paginated layout
40 
41**See full catalog**: https://docs.realtime.cloudflare.com/ui-kit
42 
43## Core SDK Patterns
44 
45### Basic Setup
46```typescript
47import RealtimeKitClient from '@cloudflare/realtimekit';
48 
49const meeting = new RealtimeKitClient({ authToken, video: true, audio: true });
50meeting.self.on('roomJoined', () => console.log('Joined:', meeting.meta.meetingTitle));
51meeting.participants.joined.on('participantJoined', (p) => console.log(`${p.name} joined`));
52await meeting.join();
53```
54 
55### Video Grid & Device Selection
56```typescript
57// Video grid
58function VideoGrid({ meeting }) {
59  const [participants, setParticipants] = useState([]);
60  useEffect(() => {
61    const update = () => setParticipants(meeting.participants.joined.toArray());
62    meeting.participants.joined.on('participantJoined', update);
63    meeting.participants.joined.on('participantLeft', update);
64    update();
65    return () => { meeting.participants.joined.off('participantJoined', update); meeting.participants.joined.off('participantLeft', update); };
66  }, [meeting]);
67  return <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(300px, 1fr))' }}>
68    {participants.map(p => <VideoTile key={p.id} participant={p} />)}
69  </div>;
70}
71 
72function VideoTile({ participant }) {
73  const videoRef = useRef<HTMLVideoElement>(null);
74  useEffect(() => {
75    if (videoRef.current && participant.videoTrack) videoRef.current.srcObject = new MediaStream([participant.videoTrack]);
76  }, [participant.videoTrack]);
77  return <div><video ref={videoRef} autoPlay playsInline muted /><div>{participant.name}</div></div>;
78}
79 
80// Device selection
81const devices = await meeting.self.getAllDevices();
82const switchCamera = (deviceId: string) => {
83  const device = devices.find(d => d.deviceId === deviceId);
84  if (device) await meeting.self.setDevice(device);
85};
86```
87 
88## React Hooks (Official)
89 
90```typescript
91import { useRealtimeKitClient, useRealtimeKitSelector } from '@cloudflare/realtimekit-react-ui';
92 
93function MyComponent() {
94  const [meeting, initMeeting] = useRealtimeKitClient();
95  const audioEnabled = useRealtimeKitSelector(m => m.self.audioEnabled);
96  const participantCount = useRealtimeKitSelector(m => m.participants.joined.size());
97  
98  useEffect(() => { initMeeting({ authToken: '<token>' }); }, []);
99  
100  return <div>
101    <button onClick={() => meeting?.self.enableAudio()}>{audioEnabled ? 'Mute' : 'Unmute'}</button>
102    <span>{participantCount} participants</span>
103  </div>;
104}
105```
106 
107**Benefits:** Automatic re-renders, memoized selectors, type-safe
108 
109## Waitlist Handling
110 
111```typescript
112// Monitor waitlist
113meeting.participants.waitlisted.on('participantJoined', (participant) => {
114  console.log(`${participant.name} is waiting`);
115  // Show admin UI to approve/reject
116});
117 
118// Approve from waitlist (backend only)
119await fetch(
120  `https://api.cloudflare.com/client/v4/accounts/${accountId}/realtime/kit/${appId}/meetings/${meetingId}/active-session/waitlist/approve`,
121  {
122    method: 'POST',
123    headers: { 'Authorization': `Bearer ${apiToken}` },
124    body: JSON.stringify({ user_ids: [participant.userId] })
125  }
126);
127 
128// Client receives automatic transition when approved
129meeting.self.on('roomJoined', () => console.log('Approved and joined'));
130```
131 
132## Audio-Only Mode
133 
134```typescript
135const meeting = new RealtimeKitClient({
136  authToken: '<token>',
137  video: false,  // Disable video
138  audio: true,
139  mediaConfiguration: {
140    audio: {
141      echoCancellation: true,
142      noiseSuppression: true,
143      autoGainControl: true
144    }
145  }
146});
147 
148// Use audio grid component
149import { RtkAudioGrid } from '@cloudflare/realtimekit-react-ui';
150<RtkAudioGrid meeting={meeting} />
151```
152 
153## Addon System
154 
155```typescript
156// List available addons
157meeting.plugins.all.forEach(plugin => {
158  console.log(plugin.id, plugin.name, plugin.active);
159});
160 
161// Activate collaborative app
162await meeting.plugins.activate('whiteboard-addon-id');
163 
164// Listen for activations
165meeting.plugins.on('pluginActivated', ({ plugin }) => {
166  console.log(`${plugin.name} activated`);
167});
168 
169// Deactivate
170await meeting.plugins.deactivate();
171```
172 
173## Backend Integration
174 
175### Token Generation (Workers)
176```typescript
177export interface Env { CLOUDFLARE_API_TOKEN: string; CLOUDFLARE_ACCOUNT_ID: string; REALTIMEKIT_APP_ID: string; }
178 
179export default {
180  async fetch(request: Request, env: Env): Promise<Response> {
181    const url = new URL(request.url);
182    
183    if (url.pathname === '/api/join-meeting') {
184      const { meetingId, userName, presetName } = await request.json();
185      const response = await fetch(
186        `https://api.cloudflare.com/client/v4/accounts/${env.CLOUDFLARE_ACCOUNT_ID}/realtime/kit/${env.REALTIMEKIT_APP_ID}/meetings/${meetingId}/participants`,
187        {
188          method: 'POST',
189          headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${env.CLOUDFLARE_API_TOKEN}` },
190          body: JSON.stringify({ name: userName, preset_name: presetName })
191        }
192      );
193      const data = await response.json();
194      return Response.json({ authToken: data.result.authToken });
195    }
196    
197    return new Response('Not found', { status: 404 });
198  }
199};
200```
201 
202## Best Practices
203 
204### Security
2051. **Never expose API tokens client-side** - Generate participant tokens server-side only
2062. **Don't reuse participant tokens** - Generate fresh token per session, use refresh endpoint if expired
2073. **Use custom participant IDs** - Map to your user system for cross-session tracking
208 
209### Performance
2101. **Event-driven updates** - Listen to events, don't poll. Use `toArray()` only when needed
2112. **Media quality constraints** - Set appropriate resolution/bitrate limits based on network conditions
2123. **Device management** - Enable `autoSwitchAudioDevice` for better UX, handle device list updates
213 
214### Architecture
2151. **Separate Apps for environments** - staging vs production to prevent data mixing
2162. **Preset strategy** - Create presets at App level, reuse across meetings
2173. **Token management** - Backend generates tokens, frontend receives via authenticated endpoint
218 
219## In This Reference
220- [README.md](README.md) - Overview, core concepts, quick start
221- [configuration.md](configuration.md) - SDK config, presets, wrangler setup
222- [api.md](api.md) - Client SDK APIs, REST endpoints
223- [gotchas.md](gotchas.md) - Common issues, troubleshooting, limits
224