Fix: Monaco Editor Not Working — Editor Not Loading, TypeScript Errors, or Web Workers Failing

The Problem

The editor mounts but shows a blank area:

import Editor from '@monaco-editor/react';

function CodeEditor() {
  return <Editor height="400px" language="typescript" value="const x = 1;" />;
  // Empty white area — no editor visible
}

Or web workers fail to load:

Error: Unexpected usage — or —
Could not create web worker(s). Falling back to loading web worker code in main thread.

Or TypeScript features (autocomplete, type checking) don’t work:

IntelliSense shows no suggestions for imported types

Why This Happens

Monaco Editor is the editor that powers VS Code. It’s powerful but complex to set up in web applications:

• Monaco loads web workers for language features — TypeScript, CSS, HTML, and JSON each have dedicated web workers for parsing, validation, and IntelliSense. If workers can’t load (wrong URL, CSP blocking, bundler misconfiguration), the editor falls back to the main thread or features break.
• The editor needs explicit dimensions — Monaco fills its container. If the container has zero height, the editor is invisible. You must set height on the Editor component or give the parent a defined height.
• TypeScript configuration is separate — Monaco has its own TypeScript compiler that runs in the browser. It doesn’t use your project’s tsconfig.json. You must configure compiler options and type definitions through the Monaco API.
• Monaco is large (~5MB) — it includes full language support for many languages. For production, consider loading it from a CDN or code-splitting.

The blank-editor failure is almost always a hydration or sizing problem rather than a Monaco bug. Monaco is a DOM-heavy library that measures its container during mount and sizes its internal layers (overlay, scrollbar, minimap, glyph margin) based on the result. If the container’s height is computed from a flex parent that hasn’t laid out yet, Monaco measures 0 and renders nothing visible. The automaticLayout: true option fixes most of these cases but adds a ResizeObserver on every editor instance — on a page with ten editors, this becomes a measurable perf cost.

The worker story is the deeper trap. Monaco ships language services (TypeScript, JSON, CSS, HTML) as separate JavaScript bundles meant to run in dedicated Web Workers. The @monaco-editor/react wrapper loads these workers from a CDN by default via the AMD loader. That works in development but breaks in production behind a strict Content Security Policy that forbids cross-origin script execution. The fallback path runs language services on the main thread, which freezes the UI on any non-trivial file. The fix is to host workers on your own origin and wire them through self.MonacoEnvironment — a setup step that’s easy to skip in early development and painful to discover when an enterprise customer reports “the editor locks up.”

The third pitfall is bundle size. A naive import Editor from '@monaco-editor/react' pulls roughly 5 MB of language services into your initial bundle. On a marketing page that includes a single code-preview widget, that’s an unacceptable performance regression. The library does not tree-shake unused languages, so the only mitigation is dynamic import with ssr: false and explicit language allowlisting through the loader API.

Production Incident Lens: When the Editor Becomes a Brick

The blast radius for a Monaco failure is the editor feature itself — but for a code-first product (a playground, a low-code platform, an admin SQL console), that feature is the product. When the chunk error appears in production, users see a permanent loading spinner or a blank rectangle. They cannot file a bug because the form to file it is rendered in the broken editor. RUM metrics show the page loaded successfully (200 OK, first contentful paint normal), so synthetic monitoring never catches the regression.

The on-call signal pattern is distinctive. Look for:

1. Sudden spike in long tasks — Monaco’s main-thread fallback creates 1–3 second blocks on the main thread during initial parse. If longTask events triple after a deploy, suspect the worker config.
2. Chunk-load errors clustered by route — Monaco lives in a dynamic chunk. If your CDN cached an old chunk hash and your new HTML references a new one, every user on the editor route gets ChunkLoadError. The fix is to keep old chunks for at least one deploy cycle.
3. Bundle size regression alerts — a careless import 'monaco-editor' in a server component pulls Monaco into every page’s bundle. Add a CI check on the editor route’s chunk size and alert on any growth above 10%.

Treat Monaco like any other large third-party widget: load it dynamically, host its workers on your own origin under a stable URL, and add a feature flag to disable it (falling back to a <textarea>) so on-call can mitigate without redeploying. A <textarea> is ugly but not broken; a stuck Monaco is broken in a way users cannot work around.

Fix 1: React Setup with @monaco-editor/react

npm install @monaco-editor/react

'use client';

import Editor from '@monaco-editor/react';
import { useState } from 'react';

function CodeEditor() {
  const [code, setCode] = useState('const greeting: string = "Hello, World!";\nconsole.log(greeting);');

  return (
    <div style={{ border: '1px solid #ccc', borderRadius: '8px', overflow: 'hidden' }}>
      <Editor
        height="400px"              // Required — explicit height
        language="typescript"
        theme="vs-dark"             // 'vs' | 'vs-dark' | 'hc-black'
        value={code}
        onChange={(value) => setCode(value || '')}
        options={{
          minimap: { enabled: false },
          fontSize: 14,
          lineNumbers: 'on',
          scrollBeyondLastLine: false,
          wordWrap: 'on',
          automaticLayout: true,     // Auto-resize when container changes
          tabSize: 2,
          formatOnPaste: true,
          formatOnType: true,
        }}
        loading={<div style={{ padding: '20px' }}>Loading editor...</div>}
      />
    </div>
  );
}

Fix 2: Access Monaco Instance for Advanced Features

'use client';

import Editor, { useMonaco, OnMount } from '@monaco-editor/react';
import { useEffect, useRef } from 'react';
import type * as Monaco from 'monaco-editor';

function AdvancedEditor() {
  const editorRef = useRef<Monaco.editor.IStandaloneCodeEditor | null>(null);
  const monaco = useMonaco();

  // Configure TypeScript compiler options
  useEffect(() => {
    if (!monaco) return;

    monaco.languages.typescript.typescriptDefaults.setCompilerOptions({
      target: monaco.languages.typescript.ScriptTarget.ESNext,
      module: monaco.languages.typescript.ModuleKind.ESNext,
      moduleResolution: monaco.languages.typescript.ModuleResolutionKind.NodeJs,
      jsx: monaco.languages.typescript.JsxEmit.React,
      strict: true,
      esModuleInterop: true,
      allowJs: true,
      noEmit: true,
    });

    // Add type definitions for IntelliSense
    monaco.languages.typescript.typescriptDefaults.addExtraLib(
      `declare module 'my-lib' {
        export function greet(name: string): string;
        export interface Config {
          theme: 'light' | 'dark';
          lang: string;
        }
      }`,
      'file:///node_modules/my-lib/index.d.ts',
    );

    // Disable built-in validation if you handle it yourself
    // monaco.languages.typescript.typescriptDefaults.setDiagnosticsOptions({
    //   noSemanticValidation: true,
    //   noSyntaxValidation: true,
    // });
  }, [monaco]);

  const handleEditorMount: OnMount = (editor, monaco) => {
    editorRef.current = editor;

    // Focus the editor
    editor.focus();

    // Add custom keyboard shortcut
    editor.addCommand(
      monaco.KeyMod.CtrlCmd | monaco.KeyCode.KeyS,
      () => {
        const code = editor.getValue();
        console.log('Save:', code);
        // Handle save
      },
    );

    // Add action to context menu
    editor.addAction({
      id: 'format-code',
      label: 'Format Code',
      keybindings: [monaco.KeyMod.Shift | monaco.KeyMod.Alt | monaco.KeyCode.KeyF],
      run: (ed) => {
        ed.getAction('editor.action.formatDocument')?.run();
      },
    });
  };

  // Get/set value programmatically
  function insertText(text: string) {
    const editor = editorRef.current;
    if (!editor) return;

    const position = editor.getPosition();
    if (position) {
      editor.executeEdits('', [{
        range: new monaco.Range(position.lineNumber, position.column, position.lineNumber, position.column),
        text,
      }]);
    }
  }

  return (
    <div>
      <button onClick={() => insertText('// TODO: ')}>Insert TODO</button>
      <Editor
        height="500px"
        language="typescript"
        theme="vs-dark"
        onMount={handleEditorMount}
        options={{ automaticLayout: true }}
      />
    </div>
  );
}

Fix 3: Custom Themes

'use client';

import { useMonaco } from '@monaco-editor/react';
import { useEffect } from 'react';

function useCustomTheme() {
  const monaco = useMonaco();

  useEffect(() => {
    if (!monaco) return;

    // Define a custom theme
    monaco.editor.defineTheme('my-dark-theme', {
      base: 'vs-dark',
      inherit: true,
      rules: [
        { token: 'comment', foreground: '6A9955', fontStyle: 'italic' },
        { token: 'keyword', foreground: 'C586C0' },
        { token: 'string', foreground: 'CE9178' },
        { token: 'number', foreground: 'B5CEA8' },
        { token: 'type', foreground: '4EC9B0' },
        { token: 'function', foreground: 'DCDCAA' },
        { token: 'variable', foreground: '9CDCFE' },
      ],
      colors: {
        'editor.background': '#1a1a2e',
        'editor.foreground': '#e0e0e0',
        'editor.lineHighlightBackground': '#2a2a4e',
        'editor.selectionBackground': '#3a3a6e',
        'editorCursor.foreground': '#60a5fa',
        'editorLineNumber.foreground': '#555580',
        'editorLineNumber.activeForeground': '#8888aa',
      },
    });
  }, [monaco]);
}

// Usage
function ThemedEditor() {
  useCustomTheme();

  return (
    <Editor
      height="400px"
      language="typescript"
      theme="my-dark-theme"
      value="const x: number = 42;"
    />
  );
}

Fix 4: Multi-File Editor with Tab Support

'use client';

import Editor from '@monaco-editor/react';
import { useState } from 'react';

interface EditorFile {
  name: string;
  language: string;
  value: string;
}

function MultiFileEditor() {
  const [files, setFiles] = useState<EditorFile[]>([
    { name: 'index.tsx', language: 'typescript', value: 'export default function App() {\n  return <div>Hello</div>;\n}' },
    { name: 'styles.css', language: 'css', value: '.container {\n  padding: 1rem;\n}' },
    { name: 'config.json', language: 'json', value: '{\n  "name": "my-app"\n}' },
  ]);
  const [activeFile, setActiveFile] = useState(0);

  function updateFile(value: string | undefined) {
    setFiles(files.map((f, i) =>
      i === activeFile ? { ...f, value: value || '' } : f
    ));
  }

  return (
    <div>
      {/* Tabs */}
      <div style={{ display: 'flex', background: '#1e1e1e', borderBottom: '1px solid #333' }}>
        {files.map((file, i) => (
          <button
            key={file.name}
            onClick={() => setActiveFile(i)}
            style={{
              padding: '8px 16px',
              background: i === activeFile ? '#2d2d2d' : 'transparent',
              color: i === activeFile ? '#fff' : '#888',
              border: 'none',
              borderBottom: i === activeFile ? '2px solid #007acc' : 'none',
              cursor: 'pointer',
              fontSize: '13px',
            }}
          >
            {file.name}
          </button>
        ))}
      </div>

      {/* Editor */}
      <Editor
        height="500px"
        language={files[activeFile].language}
        theme="vs-dark"
        value={files[activeFile].value}
        onChange={updateFile}
        path={files[activeFile].name}  // Unique path for each file's model
        options={{ automaticLayout: true }}
      />
    </div>
  );
}

Fix 5: Diff Editor

'use client';

import { DiffEditor } from '@monaco-editor/react';

function CodeDiff() {
  const original = `function greet(name) {
  console.log("Hello, " + name);
  return name;
}`;

  const modified = `function greet(name: string): string {
  console.log(\`Hello, \${name}\`);
  return \`Hello, \${name}!\`;
}`;

  return (
    <DiffEditor
      height="400px"
      language="typescript"
      theme="vs-dark"
      original={original}
      modified={modified}
      options={{
        readOnly: true,
        renderSideBySide: true,  // false for inline diff
        originalEditable: false,
      }}
    />
  );
}

Fix 6: Next.js Configuration

// next.config.mjs — configure webpack for Monaco workers
const nextConfig = {
  webpack: (config, { isServer }) => {
    if (!isServer) {
      // Monaco editor workers
      config.resolve.fallback = {
        ...config.resolve.fallback,
        fs: false,
        path: false,
      };
    }
    return config;
  },
};

export default nextConfig;

// Dynamic import — load editor only when needed
import dynamic from 'next/dynamic';

const CodeEditor = dynamic(
  () => import('@/components/CodeEditor'),
  {
    ssr: false,  // Monaco doesn't work with SSR
    loading: () => <div style={{ height: 400, background: '#1e1e1e' }}>Loading editor...</div>,
  },
);

export default function EditorPage() {
  return <CodeEditor />;
}

Still Not Working?

Blank/white area instead of editor — the container has no height. Set height="400px" on the Editor component or give the parent a CSS height. Monaco fills its container but won’t create its own height.

Web workers fail with CORS or CSP errors — Monaco loads workers from the same origin. If using a CDN, the @monaco-editor/react loader handles this automatically. For custom setups, configure MonacoEnvironment.getWorkerUrl to point to your worker files.

TypeScript IntelliSense doesn’t show — Monaco’s TypeScript language service runs separately from your project. Add type definitions with addExtraLib(). For React types, add @types/react definitions. For your own libraries, pass the .d.ts content.

Editor is slow with large files — Monaco handles large files well, but files over 10MB can cause UI lag. Disable minimap, line numbers, and syntax highlighting for very large files. Set largeFileOptimizations: true in editor options.

ChunkLoadError after deploy — your CDN cached the previous Monaco chunk under a different content hash. Users with stale HTML still reference the old hash, fail to fetch it, and see a permanent loading state. Configure your CDN to retain old chunks for 24 hours, and add a global error listener that reloads the page on ChunkLoadError.

Editor pushes Lighthouse score below 50 — the initial bundle is too large. Move the editor behind dynamic import with ssr: false, gate it behind user intent (a “Show code” button), and load workers from your own origin to avoid CDN handshake cost. For pages where the editor is below the fold, prefetch the chunk on hover instead of eagerly.

Editor mounts but value updates ignore React state — Monaco maintains its own internal model. When you pass value and the user edits, Monaco updates its model, not your React state. The onChange callback is the source of truth. If you also force-update value from props on every render, you’ll fight the user’s cursor position. Use defaultValue for read-only initialization and let Monaco own the buffer.

For related code editor issues, see Fix: Tiptap Not Working, Fix: Shiki Not Working, Fix: Webpack Bundle Too Large, and Fix: Storybook Not Working.