# monaco-editor-vite-plugin
[![Npm package version](https://badgen.net/npm/v/@bithero/monaco-editor-vite-plugin)](https://npmjs.com/package/@bithero/monaco-editor-vite-plugin) [![License](https://badgen.net/npm/license/@bithero/monaco-editor-vite-plugin)](https://codearq.net/bithero-js/monaco-editor-vite-plugin/src/branch/master/LICENSE) [![Npm package types](https://badgen.net/npm/types/@bithero/monaco-editor-vite-plugin)](https://npmjs.com/package/@bithero/monaco-editor-vite-plugin)

A vite plugin to ease bundeling of the monaco editor.

## License

This project is licensed under AGPL-3.0-or-later. See the `LICENSE` file for more informations.

Notice: This project GENERATES some code on the fly, that is INCLUDED in the final result. This code is ALSO LICENSED under AGPL-3.0-or-later!

## Usage

```ts
import { monaco } from '@bithero/monaco-editor-vite-plugin';

export default defineConfig({
    plugins: [
        monaco({
            features: "all",
            languages: ["json"],
            globalAPI: true,
        }),
    ],
});
```

> Note: in order to work correctly, the plugin needs to exclude `'monaco-editor'` from vite's dependency optimization. It does this by adding it to `optimizeDeps.exclude`, and will remove any possible entry from `optimizeDeps.include`.

### feature configuration

The `features` option enables you to enable / disable certain features of monaco.

If the key is not present, the default features of monaco are used, which is equivalent with all being activated (or a value of `*` / `all`).

When a value of `*` or `all` is set, all features are activated.

Otherwise, it is an array of either inclusions or exclusions:

- A exclusion is the featurename with a `!` prepended (like `!contextmenu`). If **any** exclusion is present, from the set of all features, the excluded ones are removed. Inclusion rules are effectivly ignored then.

- Otherwise a inclusion by just the featurename. This will only enable the features that are listed.

> Note: If using a inclusion list, codicons are not loaded by default (if not requested by any other feature). So if you'll use them inside your html, make sure to add `'codicons'` to your feature list!

### languages configuration

By default, the monaco editor comes with a set of languages (discoverable by looking into the `node_modules/monaco-editor/esm/vs/basic-languages` and `node_modules/monaco-editor/esm/vs/language` folders), that might be a overhead for your usecase. Because of this, by default no languages are included.

To change this, you can set the `languages` option:

- If set to either `*` or `all`, the default monaco behaviour is restored, by including every language.

- Otherwise it's a list of the language-names that should be available.

### custom languages

If you have an custom language, you can let it load too by using the `customLanguages` option. This option is an array of languages to be included, and needs to have the same format as the languages-metadata of core monaco (see `node_modules/monaco-editor/esm/metadata.js`).

```ts
export interface IWorkerDefinition {
	id: string;
	entry: string;
}

export interface IFeatureDefinition {
	label: string;
	entry: string | string[] | undefined;
	worker?: IWorkerDefinition;
}
```

Example:
```ts
monaco({
    customLanguages: [
        {
            label: 'my-lang',
            entry: 'some/path/to/my-lang',
        }
    ]
})
```

Both `entry` properties (once in `IFeatureDefinition` and once in `IWorkerDefinition`) are resolved with `import.meta.resolve`, which means that you can write paths as if you would write an `import` declaration in js/ts.

Additionally, the resolving is first tried with the prefix `monaco-editor/esm`, so you can easily extend & customize monaco's builtin languages.

### globalAPI

With the `globalAPI` flag, one can simply set the `self.MonacoEnvironment.globalAPI` setting.