Monaco Editor 0.57.0: only monaco.d.ts is versioned, and AMD is on the way out

monaco.d.ts is the only versioned surface, and the root package is private

Installing is one command, and what follows it is the most important sentence in the project:

> npm install monaco-editor

You get an ESM version inside /esm, compatible with e.g. webpack, and monaco.d.ts, and that type definition file is what is actually versioned, while everything else is considered private and might break with any release. So a pinned version buys you stable type signatures and nothing else. Any helper, internal namespace, or worker bootstrap you reach for outside monaco.d.ts is unprotected code. Two details in package.json sharpen this. The root package is marked "private": true, so the repository's own manifest is not what you install; you install the published artifact. And it carries a vscodeRef of 6a598d4a13031703d483d103c1d934a36ad27971, meaning a Monaco build is a snapshot of one specific VS Code commit. Combined with the stated answer that there is no relationship between VS Code's version and Monaco's version, since Monaco is a library reflecting the source directly, you cannot infer editor features from the number 0.57.0.

A model is a file that may not exist, and its URI is a one-shot resource

Models are the object you actually manage content through, and they are looser than the name suggests. A model represents a file that has been opened, which could be a file on a file system, but it does not have to be. It holds the text content, determines the language of the content, and tracks the edit history. Each model is identified by a URI, and that is precisely why two models cannot share one. If you create a model without a URI, it gets inmemory://model/1, with the number increasing as more models are created. That fallback is where smart features quietly stop working, because providers operate on models and some of them depend on the file URI: TypeScript resolving imports, or JSON IntelliSense deciding which JSON schema applies to which model. The guidance is to choose proper model URIs, treating your content as a virtual file system that matches what your users are editing, with file:/// as a reasonable base. An unnamed model does not throw; it just resolves nothing.

dispose() is the only thing standing between a remount and a dead URI

Many Monaco related objects implement a dispose() method, intended to clean up when a resource is no longer needed, and the two calls that matter are model.dispose() and disposing the editor. Calling model.dispose() unregisters the model, which frees the URI for a new model. Editors should be disposed to free up resources and remove their model listeners. In a single page application this is not optional housekeeping. Editors are user facing views attached to the DOM, and a view that is never disposed keeps its listeners attached to a model, and a model that is never disposed keeps its URI reserved, so the second time your component mounts and tries to open the same path you have a collision rather than a fresh view. The gap worth naming: the repository documents the lifecycle rule in its concepts section and stops there. The integration guide is docs/integrate-esm.md, and the framework-shaped samples are samples/browser-esm-vite-react/ and samples/browser-esm-webpack-typescript-react/. No framework-specific unmount recipe is given, so applying the rule correctly is your job.

file:// cannot create web workers, and the only symptom is a console warning

Language services create web workers to compute heavy work outside the UI thread, and the stated position is that they cost hardly anything in resource overhead and you should not worry about them as long as you get them to work. Getting them to work has one hard prerequisite that HTML5 imposes. If you see the warning Could not create web worker, the cause is that HTML5 does not allow pages loaded on file:// to create web workers, and the fix is to load the editor through a web server on http:// or https:// schemes. That is the failure mode to internalise: it is a warning plus a slower, dumber editor, not an exception, so it can reach production unnoticed. The worker discussion also points back at the cross-domain case without expanding on it here, which means the configuration where the worker and the page are served from different origins is the one you will be working out yourself. The same applies to opening the editor from a local file during development, which never works, and to previewing a built bundle by double clicking the HTML file.

AMD is deprecated, and the only AMD samples left are NW.js and legacy

The project still ships an AMD build, described as present for backwards-compatibility reasons, with the explicit warning that AMD support is deprecated and will be removed in future versions. What the samples directory shows is the migration in progress. Ten of the sample directories are ESM: browser-esm-webpack, browser-esm-webpack-small, browser-esm-webpack-typescript, browser-esm-webpack-typescript-react, browser-esm-webpack-monaco-plugin, browser-esm-esbuild, browser-esm-parcel, browser-esm-vite, browser-esm-vite-react, and electron-esm-webpack. The AMD paths survive only in samples/nwjs-amd/, samples/nwjs-amd-v2/, and samples/legacy/. Two consequences. If you copy an AMD example from an older tutorial, you have started on the branch with no future, and the deprecation notice names no target version and no replacement flag, so you have to infer the migration yourself. If you are on webpack, the maintained route is the plugin in webpack-plugin/ exercised by samples/browser-esm-webpack-monaco-plugin/, rather than hand-wiring the AMD loader. The build script package-for-smoketest also runs webpack, esbuild and vite targets, so those three bundlers are what upstream actually verifies.

VS Code extensions do not run, and the LSP exception has two conditions

The question readers ask most is whether an extension they already have will work, and the answer is No. The one exception is stated as a note rather than a promise: if the extension is fully based on the LSP, and if the language server is authored in JavaScript, then it would be possible. Both conditions are required, and the second is the one that decides most cases, because the browser cannot host a native or Node language server process. If your server is written in Rust, Go, Python, or Java, you either need a JavaScript implementation or you ship an editor with no IntelliSense, and monaco-lsp-client/ in the tree is the client path for the LSP-only case. Note also the careful wording elsewhere: providers provide smart features such as completion and hover, and this is not the same as, but often maps to, LSP features. The mapping is manual. So the honest accounting is that the VS Code extension ecosystem, usually treated as the main reason to choose this editor, is not available, and what you get instead is a provider interface you implement yourself.

No TextMate grammars, no mobile, and a Monarch playground as the replacement

Two more assets from the VS Code world are absent, and both have consequences for planning. TextMate grammars are not supported, and the project's own answer points outside itself: a separate project assembles monaco-editor, vscode-oniguruma and vscode-textmate together to bring TM grammar support into the editor. That is a third-party stack you now own, pin, and upgrade, on top of the editor itself. The in-tree alternative is a Monarch tokenizer, with a dedicated Monarch playground for adding a new language, which is more work per language but stays inside the version you depend on. Mobile is a flat no: the editor is not supported in mobile browsers or mobile web app frameworks. If phone browsers or embedded webviews are part of your product, that is not a configuration problem, it is a different editor. Taken with the extension answer, the reusable surface is narrow. The features do come from VS Code, as the fully featured code editor it is extracted from, but grammars, extensions, and mobile are all outside the extraction.

Three test systems and a webpack, esbuild and vite smoke matrix define what is verified

The build tooling tells you where the real support boundary is. The test script chains a samples check and a grammar test that runs node's test runner across src/languages/definitions. The smoke tests drive Playwright against test/smoke/playwright.config.ts, and the packaging step behind them produces builds for webpack, esbuild and vite, including a cross-origin webpack variant. A .mocharc.json also sits in the tree alongside a gulpfile.js, .azure-pipelines/, a .devcontainer/, .husky/, .prettierrc and a .nvmrc, so the repository carries both current and older machinery. What this means for an integrator is narrow but useful: webpack, esbuild and vite are the combinations upstream tests, including a cross-origin case that is the smoke test for the worker question above. If you are on Parcel, Rollup, react-scripts, or a hand-rolled worker setup, nobody upstream is checking your combination, which is exactly why the samples directory is so wide and why the project calls the interactive playground the best way to learn the editor and to produce minimal reproducible bug reports. Search the existing issues before filing, and check CHANGELOG.md for what a release changed.

Editorial conclusion

Monaco Editor fits a reader building a desktop-class code editing surface on the web with a bundler that already handles ESM and workers, who is willing to own the language service and the syntax highlighting rather than inherit them from VS Code. It does not fit a reader who wants VS Code extensions, TextMate grammars, mobile browsers, or a version number that tells them which VS Code features they have. Before you build on it, check five things: that your deployment serves over http or https rather than file, because HTML5 blocks the web workers the language services need; that every model you create has a deliberate URI, since TypeScript import resolution and JSON schema selection both key off it; that you dispose editors and models on unmount, because disposal is what frees a URI for reuse; that you are on the ESM build inside /esm rather than the deprecated AMD one; and that you read monaco.d.ts rather than reaching for internals, since the type definitions are the only versioned surface and everything else may break with any release.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes