CSL, KQL plugin for the Monaco Editor
npm install @kusto/monaco-kustoKusto 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
- /esm Contains esm version of the library
- /dev Contains an AMD version of the library
- /min Contains a minified AMD version of the library
Example at /samples/amd
1. Run npm run copyMonacoFilesAMD or yarn copyMonacoFilesAMD
where
files will need to be served as-in.
2. Using a amd module loader, import vs/language/kusto/monaco.contribution 1. The monaco editors included loader can
be made available via a global
require require by adding the script tag:
3. You should now be able to create monaco editors with language: 'kusto'. The
monaco.languages.kusto.getKustoWorker()
4. If using typeScript, add "@kusto/monaco-kusto/globalApi" to compilerOptions.types in tsconfig.json
Parcel example at /samples/parcel
1. Configure your bundler so @kusto/monaco-kusto/release/esm/kusto.worker has it's own entry pointMonacoEnvironment
2. Configure the global with either getWorkerUrl or getWorker
3. You should now be able to create monaco editors with . Themonaco.languages.kusto.getKustoWorker()
kusto worker can be reached via the monaco global:
There are 2 APIs to set a Kusto schema:
1. setSchema - the passed schema is of type ClusterType (defined in schema.ts).setSchemaFromShowSchema
The database in ROOT.database will be the one in context.
2. - a method to set a schema from the result of the.show schema as json
Kusto query . The result is a list of databases (seeResult
interface in schema.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.
1. Install Node.js 20 https://nodejs.org/
2. Run corepack enable to make the yarn package manager available (https://yarnpkg.com/getting-started/install)yarn
3. Clone repo and run in repo rootyarn watch
4. Run from /package and a http-server will automatically open the index.html
1. Set CI environment variable to "tru"
2. Run yarn build
- Run yarn test from the package folder to run all unit tests
- From the project root, run yarn test:install to install test dependencies.yarn test:it
- In the package folder:
- Run to execute tests in headless mode.yarn test:it:ui
- Run to open the tests in a browser and rebuild automatically after each change.yarn test:it:serve
- Run to start the test server and rebuild automatically after each change.yarn test:it:watch
- Run to run tests in the terminal and automatically re-run them when test files change.
> Best practice:
> Before running yarn test:it or yarn test:it:watch, first run yarn test:it:serve.test:it
> These scripts ( and test: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:
`sh`
./debug-monaco-kusto.sh
There are two ways to run the script:
- KustoWeb (default): The script is currently set up to run the kustoweb app inside Azure-Kusto-WebUX. This is the default behavior.debug-monaco-kusto.sh
- 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 .
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.
- kustoMode Sets up and registers the Kusto language in Monaco Editor, wiring together language features, workers, and configuration.
- workerManager Manages the lifecycle and communication with web workers that run language services in the background.
- kustoWorker Implements 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 the language-service-next library, 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.
- 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 lowercasedatetime()
- feat: Wrap pasted bare ISO date and datetime strings with
- 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 useSemanticColorization and useTokenColorization settings.kusto-dark2
- Renamed theme to kusto-dark
- To enable new highlighting, add the following flag when creating the Monaco editor:
javascript`
monaco.editor.create(document.getElementById('editor'), {
// current flags...
'semanticHighlighting.enabled': true,
});
- is 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: plotly is now supported in intellisense as a render command
- fix: KustoWorker#setParameters will now apply changes immediately
- feat: Kusto worker will now respect MonacoEnvironment.baseUrl
configuration 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: https://github.com/microsoft/monaco-editor/issues/2966
- fix: "monaco is not defined" errors when consuming esm files
- Moved types from global interface (monaco.languages.kusto.*) to esm indeximport { SomeType } from '@kusto/monaco-kusto
file . With this, esm@kusto/monaco-kusto/release/monaco.d.ts
consumer no longer need to include
.MonacoEnvironment.globalApi
- ESM output no longer requires to be true
- Moved content 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.MonacoEnvironment to be true@kusto/monaco-kusto
- no exports the same api as monaco.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: setSchemaFromShowSchema now 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: true in window.MonacoEnvironment declaration to have monaco on 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: RenderOptions type missing null property union variants
- fix: errors are shown twice on hover
- update language service.
- Expose formatting options
- Bug fix: union is auto-formatted into union
- Bug fix: Intellisense doesn't show columns when using this syntax materialized_view("