0
# Async Build Variants
1

2
Asynchronous syntax highlighter builds with dynamic language loading and code splitting support. These builds defer loading of the syntax highlighting engine and languages until needed, optimizing initial bundle size and rendering performance.
3

4
## Capabilities
5

6
### LightAsync (Highlight.js Async)
7

8
Async light build using highlight.js with dynamic language loading.
9

10
```javascript { .api }
11
/**
12
 * Async syntax highlighter component using highlight.js
13
 * Supports dynamic loading of languages and the core highlighter
14
 */
15
const LightAsync: React.ComponentType<SyntaxHighlighterProps> & {
16
  /** Preload the AST generator (highlight.js core) */
17
  preload: () => Promise<void>;
18
  /** Load a specific language definition */
19
  loadLanguage: (language: string) => Promise<void>;
20
  /** Check if a language is supported by available loaders */
21
  isSupportedLanguage: (language: string) => boolean;
22
  /** Check if a language is currently registered */
23
  isRegistered: (language: string) => boolean;
24
  /** Register a language definition manually */
25
  registerLanguage: (name: string, language: any) => void;
26
  /** Array of supported language identifiers */
27
  supportedLanguages: string[];
28
};
29
```
30

31
**Usage Examples:**
32

33
```javascript
34
import { LightAsync as SyntaxHighlighter } from 'react-syntax-highlighter';
35

36
// Basic usage - languages load automatically
37
const AsyncExample = () => {
38
  const code = `async function fetchData(url) {
39
  const response = await fetch(url);
40
  return response.json();
41
}`;
42

43
  return (
44
    <SyntaxHighlighter language="javascript">
45
      {code}
46
    </SyntaxHighlighter>
47
  );
48
};
49

50
// Preload for immediate highlighting
51
const PreloadExample = () => {
52
  React.useEffect(() => {
53
    SyntaxHighlighter.preload();
54
  }, []);
55

56
  return (
57
    <SyntaxHighlighter language="python">
58
      {pythonCode}
59
    </SyntaxHighlighter>
60
  );
61
};
62

63
// Manual language loading
64
const ManualLoadExample = () => {
65
  const [isReady, setIsReady] = React.useState(false);
66

67
  React.useEffect(() => {
68
    const loadLanguage = async () => {
69
      await SyntaxHighlighter.loadLanguage('rust');
70
      setIsReady(true);
71
    };
72
    loadLanguage();
73
  }, []);
74

75
  if (!isReady) return <div>Loading syntax highlighter...</div>;
76

77
  return (
78
    <SyntaxHighlighter language="rust">
79
      {rustCode}
80
    </SyntaxHighlighter>
81
  );
82
};
83
```
84

85
### PrismAsync (Prism.js Async)
86

87
Async build using Prism.js with dynamic language loading.
88

89
```javascript { .api }
90
/**
91
 * Async syntax highlighter component using Prism.js
92
 */
93
const PrismAsync: React.ComponentType<SyntaxHighlighterProps> & {
94
  /** Preload the AST generator (refractor core) */
95
  preload: () => Promise<void>;
96
  /** Load a specific language definition */
97
  loadLanguage: (language: string) => Promise<void>;
98
  /** Check if a language is supported by available loaders */
99
  isSupportedLanguage: (language: string) => boolean;
100
  /** Check if a language is currently registered */
101
  isRegistered: (language: string) => boolean;
102
  /** Register a language definition manually */
103
  registerLanguage: (name: string, language: any) => void;
104
  /** Array of supported language identifiers */
105
  supportedLanguages: string[];
106
};
107
```
108

109
**Usage Examples:**
110

111
```javascript
112
import { PrismAsync as SyntaxHighlighter } from 'react-syntax-highlighter';
113

114
// JSX highlighting with Prism async
115
const JSXExample = () => {
116
  const jsxCode = `const Button = ({ onClick, children }) => (
117
  <button
118
    className="btn btn-primary"
119
    onClick={onClick}
120
  >
121
    {children}
122
  </button>
123
);
124

125
export default Button;`;
126

127
  return (
128
    <SyntaxHighlighter language="jsx">
129
      {jsxCode}
130
    </SyntaxHighlighter>
131
  );
132
};
133
```
134

135
### PrismAsyncLight
136

137
Async light build combining Prism.js with minimal core loading.
138

139
```javascript { .api }
140
/**
141
 * Async light syntax highlighter component using Prism.js core
142
 */
143
const PrismAsyncLight: React.ComponentType<SyntaxHighlighterProps> & {
144
  /** Preload the AST generator (refractor core) */
145
  preload: () => Promise<void>;
146
  /** Load a specific language definition */
147
  loadLanguage: (language: string) => Promise<void>;
148
  /** Check if a language is supported by available loaders */
149
  isSupportedLanguage: (language: string) => boolean;
150
  /** Check if a language is currently registered */
151
  isRegistered: (language: string) => boolean;
152
  /** Register a language definition manually */
153
  registerLanguage: (name: string, language: any) => void;
154
  /** Array of supported language identifiers */
155
  supportedLanguages: string[];
156
};
157
```
158

159
### Async Methods
160

161
Dynamic loading and management methods available on async components.
162

163
```javascript { .api }
164
/**
165
 * Preload the core syntax highlighting engine
166
 * @returns Promise that resolves when the engine is loaded
167
 */
168
preload(): Promise<void>;
169

170
/**
171
 * Load a specific language definition
172
 * @param language - Language identifier to load
173
 * @returns Promise that resolves when language is loaded
174
 */
175
loadLanguage(language: string): Promise<void>;
176

177
/**
178
 * Check if a language is supported by the async loader
179
 * @param language - Language identifier to check
180
 * @returns True if language can be loaded
181
 */
182
isSupportedLanguage(language: string): boolean;
183

184
/**
185
 * Check if a language is currently registered and ready for use
186
 * @param language - Language identifier to check
187
 * @returns True if language is registered
188
 */
189
isRegistered(language: string): boolean;
190

191
/**
192
 * Manually register a language definition
193
 * @param name - Language identifier
194
 * @param language - Language definition module
195
 */
196
registerLanguage(name: string, language: any): void;
197
```
198

199
**Advanced Usage Examples:**
200

201
```javascript
202
import { LightAsync as SyntaxHighlighter } from 'react-syntax-highlighter';
203

204
// Check language support
205
const AdvancedExample = () => {
206
  const [language, setLanguage] = React.useState('javascript');
207
  const [isSupported, setIsSupported] = React.useState(false);
208

209
  React.useEffect(() => {
210
    const checkSupport = async () => {
211
      const supported = SyntaxHighlighter.isSupportedLanguage(language);
212
      setIsSupported(supported);
213
      
214
      if (supported && !SyntaxHighlighter.isRegistered(language)) {
215
        await SyntaxHighlighter.loadLanguage(language);
216
      }
217
    };
218
    
219
    checkSupport();
220
  }, [language]);
221

222
  if (!isSupported) {
223
    return <pre>{code}</pre>; // Fallback to plain text
224
  }
225

226
  return (
227
    <SyntaxHighlighter language={language}>
228
      {code}
229
    </SyntaxHighlighter>
230
  );
231
};
232

233
// Bulk language preloading
234
const BulkPreloadExample = () => {
235
  React.useEffect(() => {
236
    const preloadLanguages = async () => {
237
      const languages = ['javascript', 'python', 'java', 'cpp'];
238
      
239
      // Preload core first
240
      await SyntaxHighlighter.preload();
241
      
242
      // Load languages in parallel
243
      await Promise.all(
244
        languages.map(lang => SyntaxHighlighter.loadLanguage(lang))
245
      );
246
    };
247
    
248
    preloadLanguages();
249
  }, []);
250

251
  return (
252
    <div>
253
      {codeBlocks.map((block, index) => (
254
        <SyntaxHighlighter key={index} language={block.language}>
255
          {block.code}
256
        </SyntaxHighlighter>
257
      ))}
258
    </div>
259
  );
260
};
261
```
262

263
### Loading States and Error Handling
264

265
Managing loading states and handling errors in async components.
266

267
```javascript
268
const AsyncWithLoadingState = ({ language, code }) => {
269
  const [isLoading, setIsLoading] = React.useState(true);
270
  const [error, setError] = React.useState(null);
271

272
  React.useEffect(() => {
273
    const loadHighlighter = async () => {
274
      try {
275
        setIsLoading(true);
276
        setError(null);
277
        
278
        if (!SyntaxHighlighter.isRegistered(language)) {
279
          await SyntaxHighlighter.loadLanguage(language);
280
        }
281
      } catch (err) {
282
        setError(err.message);
283
      } finally {
284
        setIsLoading(false);
285
      }
286
    };
287

288
    loadHighlighter();
289
  }, [language]);
290

291
  if (error) {
292
    return (
293
      <pre style={{ color: 'red' }}>
294
        Error loading syntax highlighter: {error}
295
      </pre>
296
    );
297
  }
298

299
  if (isLoading) {
300
    return (
301
      <pre style={{ opacity: 0.5 }}>
302
        {code} {/* Show code while loading highlighter */}
303
      </pre>
304
    );
305
  }
306

307
  return (
308
    <SyntaxHighlighter language={language}>
309
      {code}
310
    </SyntaxHighlighter>
311
  );
312
};
313
```
314

315
### Bundle Splitting Benefits
316

317
Understanding the performance benefits of async builds.
318

319
```javascript
320
// Bundle size comparison:
321
// Standard build: ~500KB (all languages + engine)
322
// Light build: ~50KB (core only, manual registration)
323
// Async build: ~5KB initial + chunks loaded on demand
324

325
// Async loading pattern
326
const LazyCodeBlock = React.lazy(async () => {
327
  // This entire component and its dependencies load on demand
328
  const { LightAsync as SyntaxHighlighter } = await import('react-syntax-highlighter');
329
  
330
  return {
331
    default: ({ language, children }) => (
332
      <SyntaxHighlighter language={language}>
333
        {children}
334
      </SyntaxHighlighter>
335
    )
336
  };
337
});
338

339
// Usage with Suspense
340
const App = () => (
341
  <div>
342
    <h1>My App</h1>
343
    <React.Suspense fallback={<div>Loading code highlighter...</div>}>
344
      <LazyCodeBlock language="javascript">
345
        {codeString}
346
      </LazyCodeBlock>
347
    </React.Suspense>
348
  </div>
349
);
350
```
351

352
### Integration with Code Splitting
353

354
Optimal patterns for code splitting with async builds.
355

356
```javascript
357
// Route-based code splitting with syntax highlighting
358
const DocumentationPage = React.lazy(() => import('./DocumentationPage'));
359

360
// DocumentationPage.js
361
import { PrismAsync as SyntaxHighlighter } from 'react-syntax-highlighter';
362

363
const DocumentationPage = () => {
364
  // Preload on route entry
365
  React.useEffect(() => {
366
    SyntaxHighlighter.preload();
367
  }, []);
368

369
  return (
370
    <div>
371
      <h1>API Documentation</h1>
372
      {apiExamples.map(example => (
373
        <SyntaxHighlighter 
374
          key={example.id} 
375
          language={example.language}
376
        >
377
          {example.code}
378
        </SyntaxHighlighter>
379
      ))}
380
    </div>
381
  );
382
};
383

384
// App routing
385
const App = () => (
386
  <Router>
387
    <Routes>
388
      <Route path="/" element={<HomePage />} />
389
      <Route 
390
        path="/docs" 
391
        element={
392
          <React.Suspense fallback={<div>Loading...</div>}>
393
            <DocumentationPage />
394
          </React.Suspense>
395
        } 
396
      />
397
    </Routes>
398
  </Router>
399
);
400
```
401

402
## Best Practices
403

404
### Performance Optimization
405

406
```javascript
407
// Optimize async loading with caching
408
class AsyncHighlighterManager {
409
  constructor() {
410
    this.loadingPromises = new Map();
411
    this.loadedLanguages = new Set();
412
  }
413

414
  async ensureLanguage(language) {
415
    if (this.loadedLanguages.has(language)) {
416
      return; // Already loaded
417
    }
418

419
    if (this.loadingPromises.has(language)) {
420
      return this.loadingPromises.get(language); // Loading in progress
421
    }
422

423
    const promise = SyntaxHighlighter.loadLanguage(language)
424
      .then(() => {
425
        this.loadedLanguages.add(language);
426
        this.loadingPromises.delete(language);
427
      })
428
      .catch((error) => {
429
        this.loadingPromises.delete(language);
430
        throw error;
431
      });
432

433
    this.loadingPromises.set(language, promise);
434
    return promise;
435
  }
436
}
437

438
const manager = new AsyncHighlighterManager();
439

440
// Usage in components
441
const CodeBlock = ({ language, children }) => {
442
  const [isReady, setIsReady] = React.useState(false);
443

444
  React.useEffect(() => {
445
    manager.ensureLanguage(language).then(() => setIsReady(true));
446
  }, [language]);
447

448
  return isReady ? (
449
    <SyntaxHighlighter language={language}>
450
      {children}
451
    </SyntaxHighlighter>
452
  ) : (
453
    <pre>{children}</pre>
454
  );
455
};
456
```