Kusto language plugin for the Monaco Editor. It provides the following features when editing CSL, KQL files:
- Code completion
- Syntax highlighting
- Validation: Syntax errors and linting
- code folding / outlining
- Hovers
- Find definition
- find all references
- rename symbol
npm install @kusto/monaco-kusto or yarn add @kusto/monaco-kusto
/esmContains esm version of the library
Parcel example at /samples/parcel
-
Configure your bundler so
@kusto/monaco-kusto/release/esm/kusto.workerhas it's own entry point -
Configure the global
MonacoEnvironmentwith eithergetWorkerUrlorgetWorker.getWorkermust return a dedicated kusto worker for label'kusto'— a small entry file that imports both@kusto/monaco-kusto/release/esm/kusto.workerandmonaco-editor/esm/vs/editor/editor.worker. Example:// kustoWorker.ts (bundled as a worker entry) import '@kusto/monaco-kusto/release/esm/kusto.worker'; import 'monaco-editor/esm/vs/editor/editor.worker';
// main.ts import kustoWorkerUrl from './kustoWorker?url'; // or ?worker, depending on bundler import editorWorkerUrl from 'monaco-editor/esm/vs/editor/editor.worker?url'; window.MonacoEnvironment = { getWorker(_moduleId, label) { if (label === 'kusto') return new Worker(kustoWorkerUrl, { type: 'module' }); return new Worker(editorWorkerUrl, { type: 'module' }); }, };
Since monaco-editor 0.53, routing label
'kusto'to the genericeditor.workerno longer works — the worker will crash with$loadForeignModuleand completions/semantic tokens will silently fail. -
You should now be able to create monaco editors with
language: 'kusto'. The kusto worker can be reached via the monaco global:monaco.languages.kusto.getKustoWorker()
There are 2 APIs to set a Kusto schema:
setSchema- the passed schema is of typeClusterType(defined inschema.ts). The database in ROOT.database will be the one in context.setSchemaFromShowSchema- a method to set a schema from the result of the Kusto query.show schema as json. The result is a list of databases (see interfaceResultinschema.ts), so when this method is used, it also requires a cluster URI and the name of the database in context.
The schema parsing process in Monaco-Kusto involves several components, starting from the Kusto command and ending with language features in the editor. Here is how the flow works:
Below is a diagram illustrating the schema parsing flow:
To quickly try Monaco-Kusto locally, run the following command from the package folder:
yarn start
This will start a local development server and open the demo app at http://localhost:7777.
Every PR should come with a test that checks it.
- Install Node.js 20 https://nodejs.org/
- Run
corepack enableto make theyarnpackage manager available (https://yarnpkg.com/getting-started/install) - Clone repo and run
yarnin repo root - Run
yarn watchfrom /package and a http-server will automatically open the index.html
- Set CI environment variable to "tru"
- Run
yarn build
- Run
yarn testfrom the package folder to run all unit tests
- From the project root, run
yarn test:installto install test dependencies. - In the package folder:
- Run
yarn test:itto execute tests in headless mode. - Run
yarn test:it:uito open the tests in a browser and rebuild automatically after each change. - Run
yarn test:it:serveto start the test server and rebuild automatically after each change. - Run
yarn test:it:watchto run tests in the terminal and automatically re-run them when test files change.
- Run
Best practice: Before running
yarn test:itoryarn test:it:watch, first runyarn test:it:serve. These scripts (test:itandtest:it:watch) do not automatically rebuild the project, so running the server ensures your latest code is tested.
To run monaco-kusto locally inside the Azure-Kusto-WebUX project (which should exist outside this project folder with the original project name Azure-Kusto-WebUX), you can use the provided script:
./debug-monaco-kusto.shThere are two ways to run the script:
- KustoWeb (default): The script is currently set up to run the
kustowebapp inside Azure-Kusto-WebUX. This is the default behavior. - Fabric: To run the Fabric app instead, simply comment out the Step 4 section for KustoWeb and uncomment the Step 4 section for Fabric in
debug-monaco-kusto.sh.
This allows you to easily switch between running KustoWeb and Fabric for local development.
For the debug-monaco-kusto.sh script to work, ensure that your project structure resembles the following, with both monaco-kusto and Azure-Kusto-WebUX as sibling folders:
/your-workspace-root
|-- monaco-kusto
| |-- ...
| |-- debug-monaco-kusto.sh
| |-- ...
|
|-- Azure-Kusto-WebUX
`-- ...
The important part is that the Azure-Kusto-WebUX folder is a sibling to monaco-kusto, and that its node_modules folder and package.json file are at its root. The script relies on this structure to copy files and run the correct build steps.
This section provides a high-level overview of the main files and their responsibilities in the project.
-
monaco.contribution
Declares and exports the Kusto language as a Monaco Editor contribution, making it available for registration and use externally. -
kustoModeSets up and registers the Kusto language in Monaco Editor, wiring together language features, workers, and configuration. -
workerManagerManages the lifecycle and communication with web workers that run language services in the background. -
kustoWorkerImplements the actual worker logic, handling requests for language features from the main thread. -
kustoLanguageService
Implements the core logic for Kusto language features such as parsing, validation, and providing language intelligence (completion, diagnostics, etc.).
Uses thelanguage-service-nextlibrary, which was originally created in C# and migrated to TypeScript using bridgejs. -
languageFeatures
Contains adapters and implementations for Monaco Editor language features (completion, hover, formatting, folding, etc.) specific to Kusto. -
monacoInstance
Represents the Monaco Editor instance itself. It is responsible for editor creation, configuration, and interaction with the registered Kusto language features.
- fix: preserve separators between KQL queries during document formatting without changing selection or current-command formatting
- chore: upgrade
@kusto/language-service0.0.285 → 0.0.297 and@kusto/language-service-next12.2.0 → 12.4.1, restoring missing KQL keyword-completion documentation
- BREAKING: Bumped
monaco-editorpeer dependency to^0.55.0. - BREAKING: Dropped AMD support. Only ESM is shipped in this release.
- fix: update
darkOrchidsyntax highlighting color to#8229AD
- docs: add external references to semver-classification skill
- chore: bump CI Node.js version to 22
- feat: add
onSchemaUpdateCompleteevent emitter so consumers can react to schema refresh completion
- feat: support graph schema
- chore: Update @kusto/language-service-next upgrade to 12.2.0
- feat: Add maximumDepthExceeded result kind to getReferencedGlobalParams
- chore: Revert @kusto/language-service-next upgrade to 12.1.0
- chore: Update @kusto/language-service to 0.0.285
- chore: Update @kusto/language-service-next to 12.1.0
- fix: Update query operator color to adhere to accessibility standards.
- feat: Add keyboard shortcuts for changing case:
Ctrl+Shift+U: Converts current selection to uppercaseCtrl+Shift+L: Converts current selection to lowercase
- feat: Wrap pasted bare ISO date and datetime strings with
datetime()
- fix: revert the behaviour that closed the IntelliSense/completion menu when pressing
Shift+Enter(introduced in 13.0.1).
- feat: Close IntelliSense automatically when running a query with
Shift+Enter. - chore: upgrade language‑service‑next to v12.0.0.
- breaking change: upgrade monaco-editor version to 0.52.0
- fix: support multiline bracketed strings in semantic tokenization (improves syntax highlighting).
- fix: include hyphenated words in IntelliSense logic to avoid resetting suggestions when typing "-".
- feat: Upgrade language-service-next to 11.7.6.
- fix: bug in sending the full host name - database references function to use full host name to improve proxy database cross cluster scheme fetching.
- fix: database references function to use full host name to improve proxy database cross cluster scheme fetching.
- fix: cluster references function to use full host name to improve proxy clusters cross cluster scheme fetching.
- feat: update language service with chart updated.
- fix: executing the same query on a different line now correctly displays completion items.
- feat: highlight matching brackets.
- feat: Upgrade language-service-next to 11.7.3.
- feat: Upgrade language-service-next to 11.7.1.
- fix: avoid race condition on worker disposal
- fix: Parameter docstrings not shown
- fix: decrease bundle size.
- fix: dispose all monaco models when disposing the worker to prevent memory leaks.
- revert: KQL color contrast for query operators change.
- fix: KQL color contrast for query operators now complies with accessibility guidelines.
- fix: Dark mode colors are now more readable.
- fix: Explicitly export getRangeHtml from monaco.contribution to fix an issue with parcel build.
- feat: Upgrade language-service to 0.0.279.
- fix: Revert the refactor as it caused build issues
- fix: Resolved a race condition to ensure the semantic tokens provider is registered after setting the language server schema.
- fix: Fixed an issue where semantic highlighting didn't work on schema change by properly handling provider registration.
- fix: Disposed of the existing provider whenever a new one is registered to prevent memory leaks.
- Replaced syntax highlighting in Monaco-Kusto. The old method injected CSS for each KQL classified block, causing copy-to-clipboard issues. The new implementation uses:
- Monarch Tokens: Efficient syntax highlighting leveraging Monaco Editor capabilities.
- Semantic Syntax Highlighting: Uses Kusto Language Service for context-aware highlighting.
- Removed
useSemanticColorizationanduseTokenColorizationsettings. - Renamed
kusto-dark2theme tokusto-dark - To enable new highlighting, add the following flag when creating the Monaco editor:
monaco.editor.create(document.getElementById('editor'), { // current flags... 'semanticHighlighting.enabled': true, });
getRangeHtmlis a new public API for retrieving HTML content with syntax highlighting for clipboard data.
- feat: IntelliSense completion items now maintain the original order from the language service, with the most relevant option automatically focused based on the user's input.
- fix: Exclude punctuation-only syntax from completion items.
- feat: Upgrade language-service-next to 11.6.1.
- feat: Fix bugs related to last version upgrade.
- feat: Upgrade language-service-next to 11.6.0.
- feat: Modify the ordering of completion items so that columns always appear at the top.
- feat: Upgrade language-service-next to 11.5.6.
- BREAKING CHANGE: Removed the useIntellisenseV2 option; it now defaults to true.
- feat: upgrade language-service-next to 11.5.5.
- BREAKING CHANGE: addClusterToSchema know excepts databases as an object with name and alternative name instead of just a string name.
- feat: support entity groups and database alternative name
- feat:
plotlyis now supported in intellisense as a render command
- fix:
KustoWorker#setParameterswill now apply changes immediately
- feat: Kusto worker will now respect
MonacoEnvironment.baseUrlconfiguration when running in a different origin. Checkout our new example for details
- fix: Added types back to global api
- Added "themeNames" object to exports which contains the theme we register with monaco: kusto-light, kusto-dark, and kusto-dark2
- fix: Exported types don't match types used in many cases
- BREAKING CHANGE: Bumped monaco-editor peer dependency to ~0.37.0
- This version of monaco-editor no longer requires a patch to work with Parcel. Details here: microsoft/monaco-editor#2966
- fix: "monaco is not defined" errors when consuming esm files
- Moved types from global interface (
monaco.languages.kusto.*) to esm index fileimport { SomeType } from '@kusto/monaco-kusto. With this, esm consumer no longer need to include@kusto/monaco-kusto/release/monaco.d.ts. - ESM output no longer requires
MonacoEnvironment.globalApito betrue - Moved
@kusto/monaco-kusto/release/monaco.d.tscontent to@kusto/monaco-kusto/globalApi.d.ts. Original file now references this new one, and will be removed in a future release.
- Esm output not longer requires
self.MonacoEnvironmentto be true @kusto/monaco-kustono exports the same api asmonaco.languages.kusto
- Improved quality of AMD build artifacts
- BREAKING CHANGE: AMD build artifacts now include a new "main" file that contains shared code
- BREAKING CHANGE: ESM build artifacts no longer vender dependencies in a "deps" folder. node_modules imports are left as-is, and are now in package.json#dependencies
- fix: trigger suggestion when previous suggestion selected.
- fix: low color contrast for foreground/background in suggestWidget for dark theme
- fix: low color contrast for foreground/background in suggestWidget
- fix:
setSchemaFromShowSchemanow supports for external tables.
- fix: update language service to latest version. fixes issues with scan operator being shown first in completion list.
- fix: don't do kusto specific highlighting when other language is selected.
- BREAKING CHANGE: update monaco-editor-core and monaco-editor version to 0.24.0
- Usage for ESM modules: add
globalAPI: truein window.MonacoEnvironment declaration to havemonacoon the window
- fix: external table erroneously shown for materialized views
- feat: update language service
- feat: expose custom syntax error message options
- feat: update language service to support python code strings
- fix:
RenderOptionstype missingnullproperty union variants
- fix: errors are shown twice on hover
- update language service.
- Expose formatting options
- Bug fix:
union *is auto-formatted intounion*
- Bug fix: Intellisense doesn't show columns when using this syntax
materialized_view("<table name>") | where
- Bug Fix: In
mv-expand kind=arraykind is shown with a squiggly error line - Update @kusto/language-service-next
- Colorize public query options.
- Bug Fix: Format query hangs in some use cases.
- A function validation fails (shows squiggly red lines), if the function is defined with a parameter that has a default value, but it is used without passing a value for that parameter.
- Fix bug: Scalars function parameters are always showing "Table expected" error with squiggly error red line when using setSchemaFromShowSchema.
- Missing tokens are no longer added when formatting queries.
- Fix exception "Cannot read property 'getText' of null TypeError: Cannot read property 'getText' of null at e.parseDocumentV2"
- Added a sample react project
- Upgrade to latest monaco (which includes many changes amongst them accessibility improvements)
- Fix typo in 2.1.14.
- Add a theme with a darker background color.
- Fix error "Database has no tables".
- Allow formatting commands in cursor location.
- Upgrade to latest bridge.net which fixes an exception from indexOf.
- Schema with no functions was throwing "Cannot read property 'map' of undefined".
- Add DocString to onHover tooltip
- Update language service.
- Updated render kind typing to include map.
- Added
enableHoveroption to languages settingss.
- Added
onDidProvideCompletionItemsto languages settings as callback function for doComplete operations.
- Fix
getCommandsInDocumentV2not to take new lines as command.
- Fix
doRangeFormatto work with all kind of user text selection.
- Added esm release bundles.
- Added package.json scripts to replace gulp completely.
- Fix
getRenderInfoin cases where there is not with clause.
- Some more type fixes.
- Fixed typings.
- Added
getRenderInfothat returns the render command visualization options in a query.
- Added
setParametersthat set parameters to the schema without providing the entire schema.
- Added
getReferencedGlobalParamsthat returns the global (ambient) parameters that are actually being referenced in the query.
- Control command completion bug fix (updating intellisense library)
- null pointer exception fix.
- actually made the change described in 2.0.0
- [Breaking] Change default to use intellisense V2
- fix exception in CM & DM clusters when intellisenseV2 is on
- Abiltiy to get global parameters in scope (getGlobalParams)).
- Ability to injet global parameters to intellisense (in setSchema)
- Updated language service
- Fix corrupt monaco.d.ts
- Introduce a new function in language service called
getQueryParams. it will return an array of all delcared query parameters for the query on cursor.
- Fix 1.1.13 to return ranges based on 1 (as monaco expects) rather than 0 (as kusto language server returns).
- Introduce a new function in language service called
getCommandAndLocationInContext. it will return both the text and the range of the command in context.
- Update language service to latest version.
- Fix IE compatibility issue (remove new URL usage)
- Fix broken dependency on language service.
- don't suggest chart types that we do not support yet.
- don't kill web worker after 2 minutes of inactivity by default. Reason: In exterme cases where schema is very large, trying to stringify the schema in web worker causes an OOM. This is configurable though.
- Fix broken Diagnostics
- Fix vulnerability in dependency
- Support for adding and removing line comments with keyboard shortcut.
- Support hover
- Support for go-to definition, find all refrences, rename symbol.
- [Breaking] put minified versions of language serivce in npm package.
- [How to migrate]:
include the .min (minified files) rather than the unminified files (which are no longer available)
<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>
- Increase contrast of operators in syntax highlighting.
- Updated dependency @kusto/language-service-next.
- Updated dependency on @kusto/language-service.
- [Breaking] Support monaco-editor v15. This removes supprot for pre 15 versions.
- Abiltiy to suppress completion items from intellisense.
- Dark theme support (set by calling monaco.editor.setTheme('kusto.dark'))
- Don't try to run logic on disposed models.
- Format current command always formatted the 1st command.
- Removed completion options that arent' curerntly supported.
- Colorization didn't work when asked to colorize entire document
- Updated language server dependnecy to latest version.
- improve V2 intellisense colorization performance.
- V2 intellisense now correctly reverts to V1 for control commands.
- Add decimal support to V2 instllisense .
- Fix v2 intellisense.
- fix quirks in interactions between non-semantic and semantic colorization by not using semantic coloring to color plain text.
- Fixed an issue where colorization is working on an older vesion of the document, which results in wrong colorization.
- Intellisense didn't work properly when editing in the middle of a block that is not the 1st block on the page.
- Monarch colorization now colorizes sub-opeators the same as semantic colorization (which makes the changes less jarring when completing semantic colorization).
- When switching context, colorization didn't recolorize.
- (perf) Only colorize the currently edited block(s) - this supports multi-cursor editing
- (perf) don't deeply parse the entire doc when doing completion. just get the list of commands and then parse the relevant command's all tokns.
- removed semantic colorization from main thread. From now on basic colorization (schema-unaware) will happen on main thread, and semantic colorization will happen in background thread. This should improve typing performance on long rows, or on large databases.
- Support for DM intellisense
- fix incorrect column types
- upgrade to latest kusto.javascript.client (based on a newer version of bridge.net and the code itself)
- upgrade to latest Kusto.Language.Bridge (based on a newer version of bridge.net and the code itself)
- improve performance for function parsing by levaraging new functionality in Kusto.Language.Bridge.
- Update langauge service dependencies to versions with unified bridge.net version and bridge.json settings.
- [breaking] Cache clutsser schema in memory. This breaks backward compatibility since it now requries schema to include minor and major version of databases.
- Upgrade version of Kusto.Language.Bridge so solve some issues.
- enable get current command logic to V2.
- Fix ability to set schema using .show schema as json.
- fix bug that caused diagnostics and colorizaiton to be wrong until first text was typed.
- fix bug that rendered validation unusable
- Add colorization support to intellisense API v2
- Add functions support to intellisense API V2
- update version of @kusto/language-service-next to 0.0.10, integrated following functionality:
- library orders items on its own, so no need to order in monaco-kusto
- add support for the cursor not ending in the end of the completion text (like in the 1st parmaeter7 of a function for example)
- add '|' after table name
- Make sure to never parse the same text more than once.
- add diagnostics (a.k.a error message) support (when v2 parser enabled).
- add folding (a.k.a outlining) support. one can now fold commands and hide them from screen.
- [breaking] - introduce new intellisense library (off by default). requires adding the following line to code
<script src="../node_modules/kusto-language-service/kusto.javascript.client.js"></script>- [breaking] - Update monaco-editor peer dependency to "^0.12.0" because of bug fixes performed there. Also making the dependency more permissive (allow later minor versions).
- Add missing dependency bridge newtonsoft.json.js to npm package.
- updated @kusto/lagnuage-service to latest version. this contains the latest operators, documentation, and charting logic.
- Added peer dependency for
monaco-editor@0.11so that consumers of the package get a warning if their version of monaco is too old.
- [breaking] - The package now requires
monaco-editor@0.11.1to function correctly. adds support for markdown in intellisense documentation.
- Added
setSchemaFromShowSchema: a new method to set a schema from the result of .show schema as json exewcution
- [breaking]: make setSchema async so that big schemas do not block the ui thread (specifically - tokenization code is running in ui thread so it can block rendering).
- fixed label casing of
editor.action.kusto.formatCurrentCommandcommand.
- add
getAdminCommandmethod toKustoWorker, which returns an object with a boolean property signifying whether the text is an admin command, and a string property that contains the command without leading comments.
- null pointer exception when creating and destroying multiple monaco models
- add
getClientDirectivemethod toKustoWorker, which returns an object with a boolean property signifying whether the text is a client directive, and a string property that contains the directive without leading comments.
- fix getCurrentCommand bug when there are multiple commands in document
- fix intellisense issue when trying to get suggestions for a new query (2 newlines after previous query)
- command formatting and document formatting now work (ctrl K + ctrl F and alt+shift+F respectively)
- setSchema does not update syntax highlighting

