0
# Configuration
1

2
Configuration modules for enabling various Legend State features and optimizations. These functions allow you to customize Legend State's behavior and enable platform-specific optimizations.
3

4
## Capabilities
5

6
### Global Configuration
7

8
Core configuration function for Legend State settings.
9

10
```typescript { .api }
11
/**
12
 * Configures Legend State with custom observable functions and properties
13
 * @param config - Configuration object with custom functions and properties
14
 */
15
function configureLegendState(config: {
16
  observableFunctions?: Record<string, (node: NodeValue, ...args: any[]) => any>;
17
  observableProperties?: Record<string, {
18
    get: (node: NodeValue) => any;
19
    set: (node: NodeValue, value: any) => any;
20
  }>;
21
}): void;
22
```
23

24
### React Optimizations
25

26
Configuration functions for React-specific optimizations and features.
27

28
```typescript { .api }
29
/**
30
 * Enables React integration with automatic tracking
31
 * @param options - Configuration options for React tracking
32
 */
33
function enableReactTracking(options: {
34
  auto?: boolean; // Make all get() calls act as useSelector() hooks
35
  warnUnobserved?: boolean; // Warn if get() is used outside of an observer
36
}): void;
37

38
/**
39
 * Enables React components (Show, For, Switch, etc.)
40
 * Must be called before using React components
41
 */
42
function enableReactComponents(): void;
43

44
/**
45
 * Enables React Native specific components and optimizations
46
 * Use this instead of enableReactComponents for React Native
47
 */
48
function enableReactNativeComponents(): void;
49

50
/**
51
 * Enables direct rendering optimizations for React
52
 * Improves performance by bypassing some React internals
53
 */
54
function enableReactDirectRender(): void;
55

56
/**
57
 * Enables React.use() integration for Suspense
58
 * Allows observables to work with React Suspense
59
 */
60
function enableReactUse(): void;
61
```
62

63
### Performance Optimizations
64

65
Configuration functions for various performance optimizations.
66

67
```typescript { .api }
68
/**
69
 * Enables direct access optimization
70
 * Allows direct property access on observables for better performance
71
 */
72
function enableDirectAccess(): void;
73

74
/**
75
 * Enables direct peek optimization  
76
 * Optimizes peek() operations for better performance
77
 */
78
function enableDirectPeek(): void;
79
```
80

81
### History Tracking
82

83
Functions for configuring and managing observable history.
84

85
```typescript { .api }
86
/**
87
 * Tracks history of changes to an observable
88
 * @param obs - Observable to track history for
89
 * @param options - History tracking configuration
90
 * @returns History tracker instance
91
 */
92
function trackHistory<T>(
93
  obs: Observable<T>, 
94
  options?: HistoryOptions
95
): HistoryTracker<T>;
96

97
interface HistoryOptions {
98
  /** Maximum number of history entries to keep */
99
  maxSize?: number;
100
  /** Whether to track individual property changes */
101
  trackProperties?: boolean;
102
  /** Debounce time for history entries */
103
  debounce?: number;
104
}
105

106
interface HistoryTracker<T> {
107
  /** Undo the last change */
108
  undo(): boolean;
109
  /** Redo the last undone change */
110
  redo(): boolean;
111
  /** Check if undo is available */
112
  canUndo(): boolean;
113
  /** Check if redo is available */
114
  canRedo(): boolean;
115
  /** Get history entries */
116
  getHistory(): HistoryEntry<T>[];
117
  /** Clear all history */
118
  clear(): void;
119
  /** Dispose history tracking */
120
  dispose(): void;
121
}
122

123
interface HistoryEntry<T> {
124
  /** Timestamp of the change */
125
  timestamp: number;
126
  /** Previous value */
127
  previous: T;
128
  /** Current value */
129
  current: T;
130
  /** Path of the change (for property tracking) */
131
  path?: string[];
132
}
133
```
134

135
### Tracing and Debugging
136

137
Development tools for tracing and debugging observable behavior.
138

139
```typescript { .api }
140
/**
141
 * Hook to trace listener changes in React components
142
 * @param name - Optional name for the trace
143
 */
144
function useTraceListeners(name?: string): void;
145

146
/**
147
 * Hook to trace component updates and re-renders
148
 * @param name - Optional name for the trace
149
 */
150
function useTraceUpdates(name?: string): void;
151

152
/**
153
 * Hook to verify component is not tracking observables
154
 * @param name - Optional name for the verification
155
 */
156
function useVerifyNotTracking(name?: string): void;
157

158
/**
159
 * Hook to verify component renders only once
160
 * @param name - Optional name for the verification
161
 */
162
function useVerifyOneRender(name?: string): void;
163
```
164

165
### Babel Plugin
166

167
Babel transformation plugin for optimizing Legend State usage.
168

169
```typescript { .api }
170
/**
171
 * Babel plugin for Legend State optimizations
172
 * Add to your Babel configuration to enable compile-time optimizations
173
 */
174
declare const babel: {
175
  /** Plugin function for Babel configuration */
176
  default: () => any;
177
  /** Plugin options */
178
  options?: {
179
    /** Whether to optimize observable access */
180
    optimizeAccess?: boolean;
181
    /** Whether to inline simple computations */
182
    inlineComputations?: boolean;
183
  };
184
};
185
```
186

187
**Usage Examples:**
188

189
```typescript
190
// Global configuration at app startup
191
import { configureLegendState } from "@legendapp/state";
192
import { enableReactTracking } from "@legendapp/state/config/enableReactTracking";
193

194
configureLegendState({
195
  batching: true,
196
  dev: process.env.NODE_ENV === "development",
197
  onError: (error) => {
198
    console.error("Legend State error:", error);
199
    // Send to error reporting service
200
  }
201
});
202

203
// Enable React features
204
enableReactTracking();
205

206
// For React Native apps
207
import { enableReactNativeComponents } from "@legendapp/state/config/enableReactNativeComponents";
208
enableReactNativeComponents();
209

210
// Enable performance optimizations
211
import { enableDirectAccess } from "@legendapp/state/config/enableDirectAccess";
212
import { enableDirectPeek } from "@legendapp/state/config/enableDirectPeek";
213

214
enableDirectAccess();
215
enableDirectPeek();
216

217
// History tracking example
218
import { observable } from "@legendapp/state";
219
import { trackHistory } from "@legendapp/state/history";
220

221
const document$ = observable({
222
  title: "Untitled",
223
  content: "",
224
  lastModified: Date.now()
225
});
226

227
const history = trackHistory(document$, {
228
  maxSize: 50,
229
  trackProperties: true,
230
  debounce: 500
231
});
232

233
// Make some changes
234
document$.title.set("My Document");
235
document$.content.set("Hello world!");
236

237
// Undo/redo
238
if (history.canUndo()) {
239
  history.undo(); // Reverts content change
240
}
241

242
if (history.canRedo()) {
243
  history.redo(); // Reapplies content change
244
}
245

246
// Development tracing
247
import React from "react";
248
import { useObservable } from "@legendapp/state/react";
249
import { 
250
  useTraceUpdates, 
251
  useVerifyOneRender 
252
} from "@legendapp/state/trace";
253

254
function MyComponent() {
255
  // Debug hooks (only in development)
256
  if (process.env.NODE_ENV === "development") {
257
    useTraceUpdates("MyComponent");
258
    useVerifyOneRender("MyComponent");
259
  }
260
  
261
  const state$ = useObservable({ count: 0 });
262
  
263
  return (
264
    <div>
265
      <p>Count: {state$.count.get()}</p>
266
      <button onClick={() => state$.count.set(c => c + 1)}>
267
        Increment
268
      </button>
269
    </div>
270
  );
271
}
272

273
// Babel configuration (.babelrc or babel.config.js)
274
/*
275
{
276
  "plugins": [
277
    ["@legendapp/state/babel", {
278
      "optimizeAccess": true,
279
      "inlineComputations": true
280
    }]
281
  ]
282
}
283
*/
284
```
285

286
## Configuration Best Practices
287

288
### Application Startup
289

290
```typescript
291
// src/legend-state-config.ts
292
import { configureLegendState } from "@legendapp/state";
293
import { enableReactTracking } from "@legendapp/state/config/enableReactTracking";
294
import { enableReactComponents } from "@legendapp/state/config/enableReactComponents";
295

296
export function initializeLegendState() {
297
  // Global configuration
298
  configureLegendState({
299
    batching: true,
300
    dev: process.env.NODE_ENV === "development"
301
  });
302
  
303
  // Enable React integration
304
  enableReactTracking();
305
  enableReactComponents();
306
  
307
  // Enable performance optimizations in production
308
  if (process.env.NODE_ENV === "production") {
309
    const { enableDirectAccess } = require("@legendapp/state/config/enableDirectAccess");
310
    const { enableDirectPeek } = require("@legendapp/state/config/enableDirectPeek");
311
    
312
    enableDirectAccess();
313
    enableDirectPeek();
314
  }
315
}
316

317
// src/index.tsx
318
import { initializeLegendState } from "./legend-state-config";
319

320
// Initialize Legend State before rendering your app
321
initializeLegendState();
322

323
// ... rest of your app initialization
324
```
325

326
### Development vs Production
327

328
```typescript
329
// Development: Enable all debugging features
330
if (process.env.NODE_ENV === "development") {
331
  configureLegendState({
332
    dev: true,
333
    onError: (error) => {
334
      console.error("Legend State Error:", error);
335
      // Could integrate with development tools
336
    }
337
  });
338
}
339

340
// Production: Optimize for performance
341
if (process.env.NODE_ENV === "production") {
342
  configureLegendState({
343
    batching: true,
344
    dev: false
345
  });
346
  
347
  // Enable all optimizations
348
  enableDirectAccess();
349
  enableDirectPeek();
350
  enableReactDirectRender();
351
}
352
```