0
# Loader Configuration
1

2
Utilities for configuring Monaco Editor loading behavior, CDN sources, and initialization options. The loader is re-exported from the `@monaco-editor/loader` package.
3

4
## Capabilities
5

6
### Loader Instance
7

8
Monaco Editor loader providing configuration and initialization control.
9

10
```typescript { .api }
11
/**
12
 * Monaco Editor loader instance for configuration and initialization
13
 */
14
declare const loader: MonacoLoader;
15

16
interface MonacoLoader {
17
  /** Initialize Monaco Editor and return promise */
18
  init(): Promise<Monaco>;
19
  /** Configure loader options */
20
  config(options: LoaderConfig): void;
21
  /** Get current Monaco instance if already loaded */
22
  __getMonacoInstance(): Monaco | null;
23
}
24
```
25

26
**Basic Usage:**
27

28
```typescript
29
import { loader } from "@monaco-editor/react";
30

31
// Initialize Monaco manually
32
async function initializeMonaco() {
33
  try {
34
    const monaco = await loader.init();
35
    console.log("Monaco loaded:", monaco);
36
    return monaco;
37
  } catch (error) {
38
    console.error("Failed to load Monaco:", error);
39
  }
40
}
41

42
// Check if Monaco is already loaded
43
function checkMonacoStatus() {
44
  const monaco = loader.__getMonacoInstance();
45
  return monaco ? "Monaco is loaded" : "Monaco not loaded yet";
46
}
47
```
48

49
### Loader Configuration
50

51
Configure Monaco Editor loading source, paths, and initialization options.
52

53
```typescript { .api }
54
/**
55
 * Configure Monaco Editor loader settings
56
 * @param options - Loader configuration options
57
 */
58
declare function config(options: LoaderConfig): void;
59

60
interface LoaderConfig {
61
  /** Monaco Editor file paths configuration */
62
  paths?: {
63
    /** Base path for Monaco Editor files */
64
    vs?: string;
65
  };
66
  /** Internationalization configuration */
67
  "vs/nls"?: {
68
    /** Available language translations */
69
    availableLanguages?: Record<string, string>;
70
  };
71
  /** Pre-loaded Monaco instance */
72
  monaco?: Monaco;
73
}
74
```
75

76
**Configuration Examples:**
77

78
```typescript
79
import { loader } from "@monaco-editor/react";
80

81
// Use custom CDN
82
function setupCustomCDN() {
83
  loader.config({
84
    paths: {
85
      vs: 'https://cdn.jsdelivr.net/npm/monaco-editor@0.45.0/min/vs'
86
    }
87
  });
88
}
89

90
// Use local files (for offline scenarios)
91
function setupLocalFiles() {
92
  loader.config({
93
    paths: {
94
      vs: '/static/monaco-editor/min/vs'
95
    }
96
  });
97
}
98

99
// Configure internationalization
100
function setupInternationalization() {
101
  loader.config({
102
    "vs/nls": {
103
      availableLanguages: {
104
        "*": "de"  // Use German language pack
105
      }
106
    }
107
  });
108
}
109

110
// Use pre-loaded Monaco instance
111
function usePreloadedMonaco(monacoInstance) {
112
  loader.config({
113
    monaco: monacoInstance
114
  });
115
}
116
```
117

118
### Advanced Loader Patterns
119

120
#### Lazy Loading with Custom Configuration
121

122
```typescript
123
import React, { useState, useCallback } from "react";
124
import { loader } from "@monaco-editor/react";
125
import Editor from "@monaco-editor/react";
126

127
function LazyMonacoEditor() {
128
  const [isConfigured, setIsConfigured] = useState(false);
129

130
  const configureAndLoad = useCallback(async () => {
131
    if (isConfigured) return;
132

133
    // Configure before loading
134
    loader.config({
135
      paths: {
136
        vs: 'https://cdn.jsdelivr.net/npm/monaco-editor@0.45.0/min/vs'
137
      }
138
    });
139

140
    try {
141
      const monaco = await loader.init();
142
      
143
      // Post-load configuration
144
      monaco.editor.defineTheme('customTheme', {
145
        base: 'vs-dark',
146
        inherit: true,
147
        rules: [],
148
        colors: {
149
          'editor.background': '#2d2d2d',
150
        }
151
      });
152

153
      setIsConfigured(true);
154
    } catch (error) {
155
      console.error('Monaco loading failed:', error);
156
    }
157
  }, [isConfigured]);
158

159
  return (
160
    <div>
161
      {!isConfigured ? (
162
        <div>
163
          <button onClick={configureAndLoad}>Load Monaco Editor</button>
164
        </div>
165
      ) : (
166
        <Editor
167
          height="400px"
168
          language="javascript"
169
          defaultValue="// Monaco loaded with custom config"
170
          theme="customTheme"
171
        />
172
      )}
173
    </div>
174
  );
175
}
176
```
177

178
#### Environment-Specific Configuration
179

180
```typescript
181
import { loader } from "@monaco-editor/react";
182

183
function configureMonacoForEnvironment() {
184
  const isProduction = process.env.NODE_ENV === 'production';
185
  const isDevelopment = process.env.NODE_ENV === 'development';
186
  
187
  if (isProduction) {
188
    // Use CDN in production
189
    loader.config({
190
      paths: {
191
        vs: 'https://cdn.jsdelivr.net/npm/monaco-editor@0.45.0/min/vs'
192
      }
193
    });
194
  } else if (isDevelopment) {
195
    // Use local files in development for faster loading
196
    loader.config({
197
      paths: {
198
        vs: '/node_modules/monaco-editor/min/vs'
199
      }
200
    });
201
  }
202

203
  // Configure based on user preferences
204
  const userLanguage = navigator.language.split('-')[0];
205
  if (userLanguage !== 'en') {
206
    loader.config({
207
      "vs/nls": {
208
        availableLanguages: {
209
          "*": userLanguage
210
        }
211
      }
212
    });
213
  }
214
}
215
```
216

217
#### Error Handling and Fallbacks
218

219
```typescript
220
import { loader } from "@monaco-editor/react";
221

222
async function robustMonacoInitialization() {
223
  const fallbackCDNs = [
224
    'https://cdn.jsdelivr.net/npm/monaco-editor@0.45.0/min/vs',
225
    'https://unpkg.com/monaco-editor@0.45.0/min/vs',
226
    'https://cdnjs.cloudflare.com/ajax/libs/monaco-editor/0.45.0/min/vs'
227
  ];
228

229
  for (let i = 0; i < fallbackCDNs.length; i++) {
230
    try {
231
      loader.config({
232
        paths: { vs: fallbackCDNs[i] }
233
      });
234

235
      const monaco = await loader.init();
236
      console.log(`Monaco loaded from CDN ${i + 1}`);
237
      return monaco;
238
      
239
    } catch (error) {
240
      console.warn(`CDN ${i + 1} failed:`, error);
241
      
242
      if (i === fallbackCDNs.length - 1) {
243
        throw new Error('All Monaco CDN sources failed');
244
      }
245
    }
246
  }
247
}
248
```
249

250
### Performance Optimization
251

252
#### Preloading Monaco
253

254
```typescript
255
import { loader } from "@monaco-editor/react";
256

257
// Preload Monaco on app initialization
258
export async function preloadMonaco() {
259
  try {
260
    loader.config({
261
      paths: {
262
        vs: 'https://cdn.jsdelivr.net/npm/monaco-editor@0.45.0/min/vs'
263
      }
264
    });
265

266
    const monaco = await loader.init();
267
    
268
    // Pre-configure frequently used features
269
    monaco.languages.typescript.javascriptDefaults.setEagerModelSync(true);
270
    monaco.languages.typescript.typescriptDefaults.setEagerModelSync(true);
271
    
272
    return monaco;
273
  } catch (error) {
274
    console.error('Monaco preload failed:', error);
275
  }
276
}
277

278
// Call during app initialization
279
// preloadMonaco();
280
```
281

282
#### Conditional Loading
283

284
```typescript
285
import React, { useState, useEffect } from "react";
286
import { loader } from "@monaco-editor/react";
287

288
function ConditionalMonacoLoader({ shouldLoad, children }) {
289
  const [monacoReady, setMonacoReady] = useState(false);
290
  const [loading, setLoading] = useState(false);
291

292
  useEffect(() => {
293
    if (!shouldLoad || monacoReady || loading) return;
294

295
    setLoading(true);
296
    
297
    loader.config({
298
      paths: {
299
        vs: 'https://cdn.jsdelivr.net/npm/monaco-editor@0.45.0/min/vs'
300
      }
301
    });
302

303
    loader.init()
304
      .then(() => {
305
        setMonacoReady(true);
306
        setLoading(false);
307
      })
308
      .catch((error) => {
309
        console.error('Monaco loading failed:', error);
310
        setLoading(false);
311
      });
312
  }, [shouldLoad, monacoReady, loading]);
313

314
  if (!shouldLoad) {
315
    return <div>Monaco not needed yet</div>;
316
  }
317

318
  if (loading) {
319
    return <div>Loading Monaco Editor...</div>;
320
  }
321

322
  if (!monacoReady) {
323
    return <div>Ready to load Monaco</div>;
324
  }
325

326
  return children;
327
}
328
```
329

330
## Integration with Build Tools
331

332
### Webpack Configuration
333

334
```javascript
335
// webpack.config.js - Example for custom Monaco setup
336
const MonacoWebpackPlugin = require('monaco-editor-webpack-plugin');
337

338
module.exports = {
339
  plugins: [
340
    new MonacoWebpackPlugin({
341
      // Available languages
342
      languages: ['javascript', 'typescript', 'css', 'html', 'json'],
343
      // Available features
344
      features: ['coreCommands', 'find', 'folding', 'bracketMatching']
345
    })
346
  ]
347
};
348

349
// Then configure loader to use local build
350
import { loader } from "@monaco-editor/react";
351

352
loader.config({
353
  paths: {
354
    vs: '/static/vs' // Path to webpack output
355
  }
356
});
357
```
358

359
### Next.js Configuration
360

361
```typescript
362
// next.config.js
363
module.exports = {
364
  webpack: (config) => {
365
    config.module.rules.push({
366
      test: /\.worker\.js$/,
367
      use: { loader: 'worker-loader' }
368
    });
369
    return config;
370
  }
371
};
372

373
// Configure for Next.js
374
import { loader } from "@monaco-editor/react";
375

376
if (typeof window !== 'undefined') {
377
  loader.config({
378
    paths: {
379
      vs: 'https://cdn.jsdelivr.net/npm/monaco-editor@0.45.0/min/vs'
380
    }
381
  });
382
}
383
```
384

385
### Vite Configuration
386

387
```typescript
388
// vite.config.js
389
export default {
390
  optimizeDeps: {
391
    include: ['monaco-editor']
392
  },
393
  build: {
394
    rollupOptions: {
395
      external: ['monaco-editor']
396
    }
397
  }
398
};
399

400
// Configure for Vite
401
import { loader } from "@monaco-editor/react";
402

403
loader.config({
404
  paths: {
405
    vs: '/node_modules/monaco-editor/min/vs'
406
  }
407
});
408
```