0
# Light Build Variants
1

2
Lightweight syntax highlighter builds that require manual language registration for optimal bundle sizes. These builds include only the core highlighting engine without pre-bundled languages.
3

4
## Capabilities
5

6
### Light (Highlight.js Core)
7

8
Light build using highlight.js core requiring manual language registration.
9

10
```javascript { .api }
11
/**
12
 * Light syntax highlighter component using highlight.js core
13
 */
14
const Light: SyntaxHighlighterComponent & {
15
  /** Register a language definition for highlighting */
16
  registerLanguage: (name: string, language: any) => void;
17
};
18

19
type SyntaxHighlighterComponent = React.ComponentType<SyntaxHighlighterProps>;
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
import { Light as SyntaxHighlighter } from 'react-syntax-highlighter';
26
import js from 'react-syntax-highlighter/dist/esm/languages/hljs/javascript';
27
import python from 'react-syntax-highlighter/dist/esm/languages/hljs/python';
28
import docco from 'react-syntax-highlighter/dist/esm/styles/hljs/docco';
29

30
// Register languages before use
31
SyntaxHighlighter.registerLanguage('javascript', js);
32
SyntaxHighlighter.registerLanguage('python', python);
33

34
const LightExample = () => {
35
  const code = `function calculateSum(a, b) {
36
  return a + b;
37
}
38

39
console.log(calculateSum(5, 3));`;
40

41
  return (
42
    <SyntaxHighlighter language="javascript" style={docco}>
43
      {code}
44
    </SyntaxHighlighter>
45
  );
46
};
47
```
48

49
### PrismLight (Prism.js Core)
50

51
Light build using Prism.js core requiring manual language registration.
52

53
```javascript { .api }
54
/**
55
 * Light syntax highlighter component using Prism.js core
56
 */
57
const PrismLight: SyntaxHighlighterComponent & {
58
  /** Register a language definition for highlighting */
59
  registerLanguage: (name: string, language: any) => void;
60
  /** Create language aliases for existing registered languages */
61
  alias: (name: string, aliases: string | string[]) => void;
62
};
63
```
64

65
**Usage Examples:**
66

67
```javascript
68
import { PrismLight as SyntaxHighlighter } from 'react-syntax-highlighter';
69
import jsx from 'react-syntax-highlighter/dist/esm/languages/prism/jsx';
70
import typescript from 'react-syntax-highlighter/dist/esm/languages/prism/typescript';
71
import prism from 'react-syntax-highlighter/dist/esm/styles/prism/prism';
72

73
// Register languages
74
SyntaxHighlighter.registerLanguage('jsx', jsx);
75
SyntaxHighlighter.registerLanguage('typescript', typescript);
76

77
const PrismLightExample = () => {
78
  const code = `interface User {
79
  name: string;
80
  age: number;
81
}
82

83
const user: User = {
84
  name: "Alice",
85
  age: 30
86
};`;
87

88
  return (
89
    <SyntaxHighlighter language="typescript" style={prism}>
90
      {code}
91
    </SyntaxHighlighter>
92
  );
93
};
94
```
95

96
### Language Registration
97

98
Manual language registration for light builds.
99

100
```javascript { .api }
101
/**
102
 * Register a language definition for syntax highlighting
103
 * @param name - Language identifier (e.g., 'javascript', 'python')
104
 * @param language - Language definition module
105
 */
106
registerLanguage(name: string, language: any): void;
107
```
108

109
**Usage Examples:**
110

111
```javascript
112
// Single language registration
113
import { Light as SyntaxHighlighter } from 'react-syntax-highlighter';
114
import javascript from 'react-syntax-highlighter/dist/esm/languages/hljs/javascript';
115

116
SyntaxHighlighter.registerLanguage('javascript', javascript);
117

118
// Multiple language registration
119
import cpp from 'react-syntax-highlighter/dist/esm/languages/hljs/cpp';
120
import java from 'react-syntax-highlighter/dist/esm/languages/hljs/java';
121
import rust from 'react-syntax-highlighter/dist/esm/languages/hljs/rust';
122

123
const languages = [
124
  ['cpp', cpp],
125
  ['java', java], 
126
  ['rust', rust]
127
];
128

129
languages.forEach(([name, lang]) => {
130
  SyntaxHighlighter.registerLanguage(name, lang);
131
});
132

133
// Dynamic registration
134
const registerLanguageIfNeeded = async (languageName) => {
135
  try {
136
    const language = await import(`react-syntax-highlighter/dist/esm/languages/hljs/${languageName}`);
137
    SyntaxHighlighter.registerLanguage(languageName, language.default);
138
  } catch (error) {
139
    console.warn(`Language ${languageName} not found`);
140
  }
141
};
142
```
143

144
### Bundle Size Optimization
145

146
Light builds significantly reduce bundle size by including only required languages.
147

148
```javascript
149
// Compare bundle sizes:
150
// Full build: ~500KB (all languages included)
151
// Light build: ~50KB (core only, languages added as needed)
152

153
// Optimal pattern for known languages
154
import { Light as SyntaxHighlighter } from 'react-syntax-highlighter';
155
import javascript from 'react-syntax-highlighter/dist/esm/languages/hljs/javascript';
156
import css from 'react-syntax-highlighter/dist/esm/languages/hljs/css';
157
import html from 'react-syntax-highlighter/dist/esm/languages/hljs/xml'; // xml is used for HTML
158

159
// Register only the languages you need
160
const SUPPORTED_LANGUAGES = {
161
  javascript,
162
  css,
163
  html
164
};
165

166
Object.entries(SUPPORTED_LANGUAGES).forEach(([name, lang]) => {
167
  SyntaxHighlighter.registerLanguage(name, lang);
168
});
169

170
// Usage remains the same
171
<SyntaxHighlighter language="javascript" style={docco}>
172
  {code}
173
</SyntaxHighlighter>
174
```
175

176
### Custom Language Support
177

178
Adding support for languages not included in the standard distribution.
179

180
```javascript
181
// Example: Adding cURL support with highlight.js plugin
182
import { Light as SyntaxHighlighter } from 'react-syntax-highlighter';
183
import curl from 'highlightjs-curl'; // External plugin
184

185
SyntaxHighlighter.registerLanguage('curl', curl);
186

187
const CurlExample = () => {
188
  const curlCode = `curl -X POST https://api.example.com/users \\
189
  -H "Content-Type: application/json" \\
190
  -d '{"name": "John", "email": "john@example.com"}'`;
191

192
  return (
193
    <SyntaxHighlighter language="curl" style={docco}>
194
      {curlCode}
195
    </SyntaxHighlighter>
196
  );
197
};
198
```
199

200
### Migration from Full Builds
201

202
Converting from full builds to light builds for better performance.
203

204
```javascript
205
// Before (Full build - larger bundle)
206
import SyntaxHighlighter from 'react-syntax-highlighter';
207
import { docco } from 'react-syntax-highlighter/dist/esm/styles/hljs';
208

209
// After (Light build - smaller bundle)
210
import { Light as SyntaxHighlighter } from 'react-syntax-highlighter';
211
import javascript from 'react-syntax-highlighter/dist/esm/languages/hljs/javascript';
212
import docco from 'react-syntax-highlighter/dist/esm/styles/hljs/docco';
213

214
// Register required languages
215
SyntaxHighlighter.registerLanguage('javascript', javascript);
216

217
// Component usage remains identical
218
const CodeBlock = ({ code, language }) => (
219
  <SyntaxHighlighter language={language} style={docco}>
220
    {code}
221
  </SyntaxHighlighter>
222
);
223
```
224

225
## Best Practices
226

227
### Language Management
228

229
```javascript
230
// Create a centralized language registry
231
const LanguageRegistry = {
232
  registered: new Set(),
233
  
234
  async register(languageName) {
235
    if (this.registered.has(languageName)) return;
236
    
237
    try {
238
      const language = await import(
239
        `react-syntax-highlighter/dist/esm/languages/hljs/${languageName}`
240
      );
241
      SyntaxHighlighter.registerLanguage(languageName, language.default);
242
      this.registered.add(languageName);
243
    } catch (error) {
244
      console.warn(`Failed to load language: ${languageName}`);
245
    }
246
  },
247
  
248
  isRegistered(languageName) {
249
    return this.registered.has(languageName);
250
  }
251
};
252

253
// Usage in components
254
const CodeBlock = async ({ language, children }) => {
255
  await LanguageRegistry.register(language);
256
  
257
  return (
258
    <SyntaxHighlighter language={language} style={docco}>
259
      {children}
260
    </SyntaxHighlighter>
261
  );
262
};
263
```
264

265
### Performance Optimization
266

267
```javascript
268
// Preload common languages at app startup
269
const COMMON_LANGUAGES = ['javascript', 'typescript', 'python', 'json'];
270

271
const preloadLanguages = async () => {
272
  const imports = COMMON_LANGUAGES.map(async (lang) => {
273
    const module = await import(`react-syntax-highlighter/dist/esm/languages/hljs/${lang}`);
274
    return [lang, module.default];
275
  });
276
  
277
  const languages = await Promise.all(imports);
278
  languages.forEach(([name, lang]) => {
279
    SyntaxHighlighter.registerLanguage(name, lang);
280
  });
281
};
282

283
// Call during app initialization
284
preloadLanguages();
285
```