Integrate the Monaco Editor with Kusto Query Language support in your app

Article
09/30/2024

Applies to: ✅ Azure Data Explorer

You can integrate the Monaco Editor with Kusto Query Language support (monaco-kusto) into your app. Integrating monaco-kusto into your app offers you an editing experience such as completion, colorization, refactoring, renaming, and go-to-definition. It requires you to build a solution for authentication, query execution, result display, and schema exploration. It offers you full flexibility to fashion the user experience that fits your needs.

In this article, you'll learn how to add monaco-kusto to the Monaco Editor and integrate it into your app. The package is available on GitHub and on npm.

Use the following steps to integrate monaco-kusto into your app using npm.

Step 1: Install the monaco-kusto package

Step 2: Set up your app to use the monaco-kusto package

Step 3: Add your database schema to the editor

Try out the integration with our Sample project!

Prerequisites

Node.js (v6.10.3 or later)

Install the monaco-kusto package

Install the Monaco Editor npm package:
```
npm i monaco-editor
```
Note

To customize the native Monaco Editor, see Monaco Editor GitHub repo.
Install the monaco-kusto npm package:
```
npm i @kusto/monaco-kusto
```

Set up your app to use the monaco-kusto package

You can set up your app to use monaco-kusto using one of the following methods:

AMD module system
ESM (webpack)

Add the following HTML to pages where the Monaco Editor is used, such as your index.html file. They're required due to a dependency the package has on kusto-language-service.

<script src="%PUBLIC_URL%/monaco-editor/min/vs/language/kusto/bridge.min.js"></script>
<script src="%PUBLIC_URL%/monaco-editor/min/vs/language/kusto/kusto.javascript.client.min.js"></script>
<script src="%PUBLIC_URL%/monaco-editor/min/vs/language/kusto/newtonsoft.json.min.js"></script>
<script src="%PUBLIC_URL%/monaco-editor/min/vs/language/kusto/Kusto.Language.Bridge.min.js"></script>

Copy the static files from the monaco and monaco-kusto packages to the monaco-editor folder on your web server. Your app will need to access these static files.
Use monaco to load them. For examples, see the samples.

The following steps describe how to set up your app to use monaco-kusto using webpack. The default entry point for a project is the src/index.js file and the default configuration file is the src/webpack.config.js file. The following steps assume that you're using the default webpack project setup to bundle your app.

In the configuration file, add the following snippets:

Under resolve.alias, add the following aliases:

'vs/language/kusto/kustoMode': 'kustoMode',
'bridge.min': '@kusto/monaco-kusto/release/esm/bridge.min',
'kusto.javascript.client.min': '@kusto/monaco-kusto/release/esm/kusto.javascript.client.min.js',
'Kusto.Language.Bridge.min': '@kusto/monaco-kusto/release/esm/Kusto.Language.Bridge.min.js',
'Kusto': '@kusto/monaco-kusto/release/esm/Kusto.Language.Bridge.min.js',
'monaco.contribution': '@kusto/monaco-kusto/release/esm/monaco.contribution'

Under module.rules, add the following loaders and dependencies:

// Loaders
{ test: /bridge\.js/, parser: { system: false } },
{ test: /kusto\.javascript\.client\.min\.js/, parser: { system: false } },
{ test: /Kusto\.Language\.Bridge\.min\.js/, parser: { system: false } },
{ test: /kustoLanguageService/, parser: { system: false } },
// Dependencies
{ test: /Kusto\.Language\.Bridge\.min/, loader: 'exports-loader?window.Kusto!imports-loader?bridge.min,kusto.javascript.client.min' },
{ test: /kustoMonarchLanguageDefinition/, loader: 'imports-loader?Kusto' },

Under entry, add the following entry point. Make a note the worker path returned, you'll need it later.
```
`@kusto/monaco-kusto/release/esm/kusto.worker.js`
```

In the KustoLanguageService-loader.js file, add the following custom loader. It replaces the use of importScripts in the configuration file:

module.exports = function loader(source) {
    source = `var Kusto = require("@kusto/language-service-next/Kusto.Language.Bridge.min");\n${source}`;

    return source.replace(/importScripts.*/g,'');;
}

In your app, add the following code:

Define the MonacoEnvironment function on your window object. Replace <path_and_full_name_of_kusto_worker> with the worker path you noted earlier.
```
window.MonacoEnvironment = { globalAPI: true, getWorkerUrl: function() { return "<path_and_full_name_of_kusto_worker>"} };
```

Create the monaco.editor object from an HTML element:

this.editor = monaco.editor.create(editorElement, editorConfig)

Call the monaco.contribution API to register the Kusto language:

import('monaco.contribution').then(async (contribution: any) => {
    const model = this.monaco && this.monaco.editor.createModel("", 'kusto');
    this.editor.setModel(model);
    const workerAccessor: monaco.languages.kusto.WorkerAccessor = await monaco.languages.kusto.getKustoWorker();
    const worker: monaco.languages.kusto.KustoWorker = await workerAccessor(model.uri);
})

Add your database schema to the editor

The monaco-kusto package provides a way to add your database schema to the editor. The schema enables the editor to provide auto-complete suggestions and other features.

Use the following structure to define the schema:

const schema = {... <YOUR_DATABASE_SCHEMA> ...};

export function setSchema(editor) {
  window.monaco.languages.kusto.getKustoWorker().then((workerAccessor) => {
    const model = editor.getModel();
    workerAccessor(model.uri).then((worker) => {
      //EITHER: Set schema from a show schema command
      // worker.setSchemaFromShowSchema(
      //     schema,
      //     clusterURI,
      //     database
      // );
      //OR: Set schema from a manually created schema
      // worker.setSchema(schema);
    });
  });
}

You can get your database schema using one of the following methods:

From your query environment
Create manually

In your query environment, select the database for which you want to create a schema.
In the query window, run the following query:
```
.show schema as json
```
Copy the result of the query and paste it as the schema constant. The result of the query is a list of databases (see interface Result in the schema.ts file).
Use the setSchemaFromShowSchema() method to set the schema in the editor. You must also specify the database URI and the name of the database to use in the editor.

Create a schema object that contains the database schema. For more information, see the clusterType interface in the src/schema.ts file. The following example shows a schema object that contains a single database and a single table:

{
  "clusterType":"Engine",
  "cluster":{
    "connectionString":"<CONNECTION_STRING>",
    "databases":[ {
      "database": {
        "name": "<DATABASE_NAME>",
        "majorVersion": 5,
        "minorVersion": 0,
        "tables": [ {
          "name": "<TABLE_NAME>",
          "entityType": "Table",
          "columns": [ {
            "name": "<COLUMN_NAME>",
            "type": "<COLUMN_TYPE>"
          }, ... ]
        }, ... ]
      }
    }, ... ]
  },
  // Defines schema for the required database.
  // The schema must also be defined in the cluster object.
  "database": {
    "name": "<DATABASE_NAME>",
    "majorVersion": 5,
    "minorVersion": 0,
    "tables": [ {
      "name": "<TABLE_NAME>",
      "entityType": "Table",
      "columns": [ {
        "name": "<COLUMN_NAME>",
        "type": "<COLUMN_TYPE>"
      }, ... ]
    }, ... ]
  }
}

Use the setSchema() method to set the schema in the editor.

Sample project

You can find a sample project that uses the monaco-kusto package. To use the sample, clone the monaco-kusto GitHub repo. You'll find the sample in the samples/react folder.

Set up and test your sample project

Run the following commands from the root of the cloned repo:

Install dependencies and build the project:
```
npm install
```
Verify the project is working. If successful, the index.html will open.
```
npm run watch
```