Improve documentation

2025-12-22 19:42:56 +01:00 · 2018-03-14 14:44:58 +01:00 · 2018-03-14 14:44:58 +01:00 · b8a3d0a727
commit b8a3d0a727
parent 2d54688825
5 changed files with 172 additions and 90 deletions
--- a/docs/integrate-amd-cross.md
+++ b/docs/integrate-amd-cross.md
@ -0,0 +1,41 @@
+## Integrating the AMD version of the Monaco Editor in a cross-domain setup
+
+Here is the most basic HTML page that embeds the editor, using AMD, in the case that the editor sources are hosted on a different domain (e.g. CDN) than the document origin.
+
+More self-contained samples are available at [monaco-editor-samples](https://github.com/Microsoft/monaco-editor-samples).
+
+If you are hosting your `.js` on a different domain (e.g. on a CDN) than the HTML, you should know that the Monaco Editor creates web workers for smart language features. Cross-domain web workers are not allowed, but here is how you can proxy their loading and get them to work:
+
+Assuming the HTML lives on `www.mydomain.com` and the editor is hosted on `www.mycdn.com`.
+
+* `https://www.mydomain.com/index.html`:
+```html
+<script type="text/javascript" src="http://www.mycdn.com/monaco-editor/min/vs/loader.js"></script>
+<script>
+	require.config({ paths: { 'vs': 'http://www.mycdn.com/monaco-editor/min/vs' }});
+
+	// Before loading vs/editor/editor.main, define a global MonacoEnvironment that overwrites
+	// the default worker url location (used when creating WebWorkers). The problem here is that
+	// HTML5 does not allow cross-domain web workers, so we need to proxy the instantiation of
+	// a web worker through a same-domain script
+	window.MonacoEnvironment = {
+		getWorkerUrl: function(workerId, label) {
+			return 'monaco-editor-worker-loader-proxy.js';
+		}
+	};
+
+	require(["vs/editor/editor.main"], function () {
+		// ...
+	});
+</script>
+```
+
+* `https://www.mydomain.com/monaco-editor-worker-loader-proxy.js`:
+```js
+self.MonacoEnvironment = {
+    baseUrl: 'http://www.mycdn.com/monaco-editor/min/'
+};
+importScripts('www.mycdn.com/monaco-editor/min/vs/base/worker/workerMain.js');
+```
+
+That's it. You're good to go! :)
--- a/docs/integrate-amd.md
+++ b/docs/integrate-amd.md
@ -0,0 +1,34 @@
+## Integrating the AMD version of the Monaco Editor
+
+Here is the most basic HTML page that embeds the editor using AMD.
+
+More self-contained samples are available at [monaco-editor-samples](https://github.com/Microsoft/monaco-editor-samples).
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta http-equiv="Content-Type" content="text/html;charset=utf-8" >
+</head>
+<body>
+
+<div id="container" style="width:800px;height:600px;border:1px solid grey"></div>
+
+<script src="monaco-editor/min/vs/loader.js"></script>
+<script>
+    require.config({ paths: { 'vs': 'monaco-editor/min/vs' }});
+    require(['vs/editor/editor.main'], function() {
+        var editor = monaco.editor.create(document.getElementById('container'), {
+            value: [
+                'function x() {',
+                '\tconsole.log("Hello world!");',
+                '}'
+            ].join('\n'),
+            language: 'javascript'
+        });
+    });
+</script>
+</body>
+</html>
+```
--- a/docs/integrate-esm.md
+++ b/docs/integrate-esm.md
@ -0,0 +1,78 @@
+## Integrating the ESM version of the Monaco Editor
+
+### Using webpack
+
+Here is the most basic script that imports the editor using ESM with webpack.
+
+More self-contained samples are available at [monaco-editor-samples](https://github.com/Microsoft/monaco-editor-samples).
+
+* `index.js`
+```js
+import * as monaco from 'monaco-editor';
+
+// Since packaging is done by you, you need
+// to instruct the editor how you named the
+// bundles that contain the web workers.
+self.MonacoEnvironment = {
+    getWorkerUrl: function (moduleId, label) {
+        if (label === 'json') {
+            return './json.worker.bundle.js';
+        }
+        if (label === 'css') {
+            return './css.worker.bundle.js';
+        }
+        if (label === 'html') {
+            return './html.worker.bundle.js';
+        }
+        if (label === 'typescript') {
+            return './ts.worker.bundle.js';
+        }
+        return './editor.worker.bundle.js';
+    }
+}
+
+monaco.editor.create(document.getElementById('container'), {
+    value: [
+        'function x() {',
+        '\tconsole.log("Hello world!");',
+        '}'
+    ].join('\n'),
+    language: 'javascript'
+});
+```
+
+* `webpack.config.js`:
+```js
+const path = require('path');
+const webpack = require('webpack');
+
+module.exports = {
+    entry: {
+        "app": './index.js',
+        // Package each language's worker and give these filenames in `getWorkerUrl`
+        "editor.worker": 'monaco-editor/esm/vs/editor/editor.worker.js',
+        "json.worker": 'monaco-editor/esm/vs/language/json/json.worker',
+        "css.worker": 'monaco-editor/esm/vs/language/css/css.worker',
+        "html.worker": 'monaco-editor/esm/vs/language/html/html.worker',
+        "ts.worker": 'monaco-editor/esm/vs/language/typescript/ts.worker',
+    },
+    output: {
+        filename: '[name].bundle.js',
+        path: path.resolve(__dirname, 'dist')
+    },
+    module: {
+        rules: [{
+            test: /\.css$/,
+            use: [ 'style-loader', 'css-loader' ]
+        }]
+    },
+    plugins: [
+        // Ignore require() calls in vs/language/typescript/lib/typescriptServices.js
+        new webpack.IgnorePlugin(
+            /^((fs)|(path)|(os)|(crypto)|(source-map-support))$/,
+            /vs\/language\/typescript\/lib/
+        )
+    ]
+};
+
+```