# @uifabric/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`, plus 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.)
- `monaco-typescript.d.ts`: Proper typings for various things used/returned by `monaco.typescript`, including `TypeScriptWorker` (generated by merging `monaco-typescript/release/esm/*.d.ts`)
- `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('@uifabric/monaco-editor/scripts/addMonacoWebpackConfig');

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

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.
- `includeAllLanguages` (`boolean`):
  - `false` (default): Imports for `@uifabric/monaco-editor` will be remapped to `@uifabric/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 `@uifabric/monaco-editor` will be remapped to `@uifabric/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 '@uifabric/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 `@uifabric/monaco-editor`, it will automatically call `configureEnvironment` with the global object.

(This works because the Webpack config remaps `@uifabric/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 '@uifabric/monaco-editor';
```

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

If you need types from `monaco-typescript`, import as follows:

```js
import { TypeScriptWorker } from '@uifabric/monaco-editor/monaco-typescript.d';
```

Note that you may run into conflicts with these types if you're on a different TypeScript version than the one the typings were generated against.