# @fluentui/monaco-editor

Version of [`monaco-editor`](https://www.npmjs.com/package/monaco-editor) with the CSS files transformed to JS which can be loaded onto the page using `@microsoft/load-themed-styles`. Also includes some Webpack configuration helpers.

## Package contents

- `esm/*`: Copy of `monaco-editor/esm/*` but with the CSS files transformed. (This package doesn't include the AMD variant since it has a built-in CSS loader.)
- `scripts/addMonacoWebpackConfig.js`: Add Monaco-related webpack configuration
- `lib/configureEnvironment.js`: Set up `MonacoEnvironment` runtime config

## How to use with Webpack

### 1. Webpack configuration

In your `webpack.config.js`, call the `addMonacoWebpackConfig` helper to add Monaco-related configuration (note that it returns a new configuration object):

```js
const { addMonacoWebpackConfig } = require('@fluentui/monaco-editor/scripts/addMonacoWebpackConfig');

// Somewhere in this file, call:
config = addMonacoWebpackConfig(originalConfig, options);
```

Parameters:

- `config` (`webpack.Configuration`): Your configuration object. Its `entry` **must** be an object (not an array or function), and the `output.globalObject` setting (if any) will be ignored.
- `options` (object, optional):
  - `outDir` (`string`, optional): output directory where font files should be copied (requires `copy-webpack-plugin` to be installed)
  - `includeAllLanguages` (`boolean`, optional):
  - `false` (default): Imports for `@fluentui/monaco-editor` will be remapped to `@fluentui/monaco-editor/lib/monacoCoreBundle`, which includes only core editor features and TypeScript language features. Entry configs will be added for the main editor worker (`editor.worker.js`) and TS worker (`ts.worker.js`) but not other languages.
  - `true`: Imports for `@fluentui/monaco-editor` will be remapped to `@fluentui/monaco-editor/lib/monacoBundle`, which includes all language contributions. Also, entry configs will be added for CSS/HTML/JSON workers in addition to TS.

### 2. Runtime configuration

This project provides two options for setting up global Monaco configuration at runtime. The options are outlined below, but both involve a config object with the following properties:

- `baseUrl` (`string`): CDN path or other path where built files are served from. (`.` is typical for local serve builds and other non-CDN scenarios.)
- `useMinified` (`boolean`, optional): Whether to use the `.min` versions of the files. (Assumes you have an additional "production mode" webpack config which generates `.min` versions of all `entry` entries.)
- `crossDomain` (`boolean`, optional): Whether to use a configuration variant which works when this script lives on a different domain than the core Monaco scripts.

#### Option A: Manual

In a root file for your project, import and call the configuration helper manually:

```js
import { configureEnvironment } from '@fluentui/monaco-editor/lib/configureEnvironment';

configureEnvironment(config);
```

This lightweight helper sets up the global `MonacoEnvironment` required for Monaco to load the worker files generated by the webpack config (it doesn't import any actual Monaco files). Its `config` parameter is the simple configuration object described above.

#### Option B: Automatic using global

Somewhere in a root file for your project (the Fluent UI React projects do this in `index.html`), define a global variable `MonacoConfig` with the properties described above. Basic example:

```js
window.MonacoConfig = {
  baseUrl: '.',
  useMinified: false,
};
```

Then the first time you import `@fluentui/monaco-editor`, it will automatically call `configureEnvironment` with the global object.

(This works because the Webpack config remaps `@fluentui/monaco-editor` imports to point to either `lib/monacoBundle` or `lib/monacoCoreBundle`, both of which re-export Monaco things and call `configureEnvironment` as a side effect.)

### 3. Using the editor

When you're ready to use the editor, import as follows:

```js
import * as monaco from '@fluentui/monaco-editor';
```

See the [Monaco documentation](https://microsoft.github.io/monaco-editor) for further usage instructions.