Rollup Monaco Bundler

Common errors

• Error: "[name] is not exported by [module]"

  cause A module, likely a CommonJS dependency of Monaco, is being imported as an ES Module, but Rollup cannot determine the correct export. Often occurs when `@rollup/plugin-commonjs` is missing or incorrectly placed.
  fix Ensure `@rollup/plugin-commonjs` is installed and included in your `rollup.config.ts` plugins array, placed *after* `@rollup/plugin-node-resolve` and *before* `@rollup/plugin-typescript` if both are present. You might need to add specific `namedExports` configurations to `@rollup/plugin-commonjs` for problematic modules.

• Monaco editor worker files are not found or fail to load.

  cause Monaco editor relies on web workers for language services. If the worker scripts are not correctly bundled, served from the correct path, or if their URLs are misconfigured, they will fail to load, preventing the editor from fully functioning.
  fix Ensure your Rollup configuration correctly handles copying or bundling worker scripts to the output directory and that the Monaco editor's global configuration (`monaco.config`) points to the correct `vs` path where these workers are located. This might involve using `rollup-plugin-copy` or similar.

• TypeError: Cannot read properties of undefined (reading 'config') or similar when loading Monaco.

  cause This often happens if the global `monaco` object is not correctly initialized or if `monaco-editor` is being loaded multiple times or in an incompatible way (e.g., mixing CDN-loaded Monaco with a bundled version).
  fix Ensure `monaco-editor` is loaded consistently, either entirely via a bundler (using `rollup-monaco-bundler` and other plugins) or entirely via a CDN. Avoid duplicate or conflicting `monaco.config` calls. Verify that the Monaco loader configuration, if used, is applied correctly before editor initialization.

Warnings

• breaking `monaco-editor` itself has transitioned heavily towards ESM builds, deprecating its AMD build. While `rollup-monaco-bundler` aims for UMD, direct integration with the latest `monaco-editor` versions (0.50.0+ as of early 2026) might require careful configuration or may not be fully compatible with older patterns used by this bundler, potentially leading to build failures or unexpected runtime behavior.
  Fix: Review `monaco-editor`'s changelog for breaking changes related to its module format. Ensure your Rollup configuration explicitly handles ESM imports if using modern Monaco versions, potentially requiring additional plugins like `@rollup/plugin-commonjs` and `@rollup/plugin-node-resolve` configured correctly, and consider if `rollup-monaco-bundler` still meets your needs for newer Monaco versions.
• gotcha To effectively bundle `monaco-editor` and its dependencies, `rollup-monaco-bundler` must be used alongside other essential Rollup plugins such as `@rollup/plugin-typescript` (for `rollup.config.ts` and source files), `@rollup/plugin-node-resolve` for resolving `node_modules` paths, and `@rollup/plugin-commonjs` for handling CommonJS modules. Failing to include or correctly configure these plugins will likely result in build errors.
  Fix: Always include `@rollup/plugin-typescript`, `@rollup/plugin-node-resolve`, and `@rollup/plugin-commonjs` in your Rollup configuration's `plugins` array. Ensure `@rollup/plugin-node-resolve` and `@rollup/plugin-commonjs` are placed before `monacoNlsInject` and any custom source processing plugins. For TypeScript, `plugin-typescript` should typically be early.
• gotcha The `monaco-editor` can produce very large bundles, impacting load times. This bundler aims to help with NLS, but overall bundle size requires careful configuration of Monaco features, languages, and potentially aggressive tree-shaking or dynamic imports.
  Fix: Utilize Monaco's own options to include only necessary languages and features. Consider dynamically importing the Monaco editor only when needed. Configure Rollup's `external` option to exclude Monaco if you intend to load it from a CDN or a separate bundle.
• gotcha Rollup configuration files (e.g., `rollup.config.js` or `rollup.config.ts`) themselves are typically treated as ES Modules by modern Rollup versions. Mixing CommonJS (`require`) syntax in a TypeScript configuration or expecting global variables like `__dirname` to work without special handling can lead to errors.
  Fix: Write your `rollup.config.ts` file using ES Module syntax (`import`/`export default`). If you need CommonJS-specific variables, you may need to use `import.meta.url` and `path` utilities to derive them for ESM contexts.

Install

• npm install rollup-monaco-bundler npm
• yarn add rollup-monaco-bundler yarn
• pnpm add rollup-monaco-bundler pnpm

Imports

• RollupMonacoBundler
  wrong:

  const RollupMonacoBundler = require('rollup-monaco-bundler');

  correct:

  import { RollupMonacoBundler } from 'rollup-monaco-bundler';

  Primarily an ESM module. `RollupMonacoBundler` is intended to generate or assist in creating a Rollup configuration.
• monacoNlsInject
  wrong:

  import monacoNlsInject from 'rollup-monaco-bundler/nls';

  correct:

  import { monacoNlsInject } from 'rollup-monaco-bundler';

  The `monacoNlsInject` function is a Rollup plugin factory for handling NLS injection.
• Rollup options

  import type { RollupOptions } from 'rollup';

  When writing `rollup.config.ts`, import Rollup's types for better IntelliSense and type checking.

Quickstart

Demonstrates a basic Rollup configuration using `monacoNlsInject` to bundle `monaco-editor` with dynamic NLS, outputting a UMD bundle.

import { defineConfig } from 'rollup';
import { monacoNlsInject } from 'rollup-monaco-bundler';
import typescript from '@rollup/plugin-typescript';
import { nodeResolve } from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';

export default defineConfig({
  input: 'src/index.ts',
  output: {
    dir: 'dist',
    format: 'umd',
    name: 'MonacoEditorBundle',
    sourcemap: true,
  },
  plugins: [
    nodeResolve(),
    commonjs(),
    typescript(),
    monacoNlsInject({
      locale: process.env.MONACO_LOCALE || 'en',
      // Other options like 'basePath', 'ignore' can be configured here.
      // Refer to the plugin documentation for full options.
    }),
    // Other Rollup plugins for CSS, assets, etc. may be needed
  ],
  external: [
    // List any modules that should not be bundled here, e.g., 'monaco-editor'
    // if you intend to load it separately or from a CDN.
  ]
});