# BoxLang Monaco Editor Monaco Editor language support for BoxLang - providing syntax highlighting, IntelliSense, and custom themes for BoxLang development. {% @github-files/github-code-block url="" %} {% embed url="" %} [![npm version](https://badge.fury.io/js/boxlang-monaco-editor.svg)](https://www.npmjs.com/package/boxlang-monaco-editor) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ### Screenshots #### BoxLang Script Syntax Highlighting
#### BoxLang Template Syntax Highlighting
### Installation ```bash npm install boxlang-monaco-editor monaco-editor ``` ### Quick Start ```javascript import * as monaco from 'monaco-editor'; import { initializeBoxLangSupport, createBoxLangEditor } from 'boxlang-monaco-editor'; // Initialize BoxLang support initializeBoxLangSupport(); // Create a BoxLang editor const editor = createBoxLangEditor(document.getElementById('editor'), { value: 'class { function init() { return this; } }', language: 'boxlang', theme: 'boxlang-theme' }); ``` ### Features * **Syntax Highlighting**: Full support for BoxLang script (.bx, .bxs) and template (.bxm) files * **IntelliSense**: Auto-completion for BoxLang keywords, functions, and constructs * **Custom Theme**: BoxLang-branded color theme featuring the signature cyan-blue gradient from the official logo * **Template Support**: Mixed HTML/BoxLang template highlighting * **Code Folding**: Intelligent folding for functions, classes, and blocks * **Bracket Matching**: Automatic bracket and quote pairing ### API Reference #### Core Functions **`initializeBoxLangSupport()`** Initializes BoxLang language support in Monaco Editor. This registers the language, sets up syntax highlighting, and applies the theme. ```javascript import { initializeBoxLangSupport } from 'boxlang-monaco-editor'; initializeBoxLangSupport(); ``` **`createBoxLangEditor(container, options)`** Creates a Monaco Editor instance configured for BoxLang. **Parameters:** * `container` (HTMLElement): DOM element to host the editor * `options` (Object): Monaco Editor configuration options **Returns:** Monaco Editor instance ```javascript import { createBoxLangEditor } from 'boxlang-monaco-editor'; const editor = createBoxLangEditor(document.getElementById('editor'), { value: 'component { function init() { return this; } }', language: 'boxlang', theme: 'boxlang-theme', automaticLayout: true }); ``` **`getBoxLangLanguage()`** Returns the registered BoxLang language configuration. ```javascript import { getBoxLangLanguage } from 'boxlang-monaco-editor'; const language = getBoxLangLanguage(); ``` #### Constants **Language IDs** * `BOXLANG_LANGUAGE_ID`: `'boxlang'` - For script files (.bx, .bxs) * `BOXLANG_TEMPLATE_LANGUAGE_ID`: `'boxlang-template'` - For template files (.bxm) **File Extensions** * `BOXLANG_EXTENSIONS`: `['.bx', '.bxs']` - BoxLang script file extensions * `BOXLANG_TEMPLATE_EXTENSIONS`: `['.bxm']` - BoxLang template file extensions **MIME Types** * `BOXLANG_MIME_TYPES`: `['text/x-boxlang']` * `BOXLANG_TEMPLATE_MIME_TYPES`: `['text/x-boxlang-template']` #### Individual Components If you need more control, you can import and configure individual components: ```javascript import { boxlangLanguageConfig } from 'boxlang-monaco-editor'; import { boxlangMonarchTokens } from 'boxlang-monaco-editor'; import { boxlangTheme } from 'boxlang-monaco-editor'; // Manual setup monaco.languages.register({ id: 'boxlang' }); monaco.languages.setLanguageConfiguration('boxlang', boxlangLanguageConfig); monaco.languages.setMonarchTokensProvider('boxlang', boxlangMonarchTokens.script); monaco.editor.defineTheme('boxlang-theme', boxlangTheme); ``` ### Development 1. **Install dependencies**: ```bash npm install ``` 2. **Start development server**: ```bash npm run dev ``` This will start Vite's development server at with hot module replacement for fast development. 3. **Build library for production**: ```bash npm run build ``` This builds the library for production using Rollup. 4. **Preview production build**: ```bash npm run preview ``` This serves the demo locally for testing. Note: The demo is for development purposes only and doesn't produce a production build. ### File Structure ``` boxlang-monaco-editor/ ├── src/ │ ├── demo/ │ │ ├── index.html # Demo page │ │ └── index.js # Demo application │ ├── index.js # Main library entry point │ ├── boxlang-language-config.js # Language configuration │ ├── boxlang-monarch-tokens.js # Syntax tokenizer │ └── boxlang-theme.js # Custom color theme ├── dist/ # Production build output ├── package.json ├── vite.config.js # Vite configuration └── rollup.config.js # Rollup config for library builds ``` ### Integration Guide #### Basic Setup To integrate BoxLang support into your own Monaco Editor instance: ```javascript import * as monaco from "monaco-editor"; import { boxlangLanguageConfig } from "boxlang-monaco-editor/boxlang-language-config"; import { boxlangMonarchTokens } from "boxlang-monaco-editor/boxlang-monarch-tokens"; import { boxlangTheme } from "boxlang-monaco-editor/boxlang-theme"; // Register BoxLang language monaco.languages.register( { id: "boxlang" } ); monaco.languages.register( { id: "boxlang-template" } ); // Set language configuration monaco.languages.setLanguageConfiguration( "boxlang", boxlangLanguageConfig ); monaco.languages.setLanguageConfiguration( "boxlang-template", boxlangLanguageConfig ); // Set syntax highlighting monaco.languages.setMonarchTokensProvider( "boxlang", boxlangMonarchTokens.script ); monaco.languages.setMonarchTokensProvider( "boxlang-template", boxlangMonarchTokens.template ); // Define custom theme monaco.editor.defineTheme( "boxlang-theme", boxlangTheme ); // Create editor const editor = monaco.editor.create( document.getElementById( "container" ), { value: "component { function init() { return this; } }", language: "boxlang", theme: "boxlang-theme" } ); ``` #### File Extension Mapping Configure your application to map file extensions to the appropriate language: ```javascript function getLanguageForFile( filename ) { const ext = filename.split( "." ).pop().toLowerCase(); switch ( ext ) { case "bx": case "bxs": return "boxlang"; case "bxm": return "boxlang-template"; default: return "plaintext"; } } ``` #### Custom Completion Provider The integration includes a basic completion provider. You can extend it with your own completions: ```javascript monaco.languages.registerCompletionItemProvider( 'boxlang', { provideCompletionItems: function( model, position ) { // Your custom completion logic here return { suggestions: [ { label: 'myCustomFunction', kind: monaco.languages.CompletionItemKind.Function, insertText: 'myCustomFunction( $1 )', insertTextRules: monaco.languages.CompletionItemInsertTextRule.InsertAsSnippet, documentation: 'My custom function' } ] }; } }); ``` ### Supported Features #### BoxLang Script Files (.bx, .bxs) * Component declarations * Function definitions * Class syntax with inheritance * Interface definitions * Property declarations * Annotations (@inject, @cacheable, etc.) * Control flow (if/else, loops, switch) * Exception handling (try/catch/finally) * Variable declarations and scoping * Operators and expressions #### BoxLang Template Files (.bxm) * HTML markup * BoxLang script blocks (``) * BoxLang components (``, ``, etc.) * String interpolation (`#variable#`) * BoxLang comments (``) * Mixed HTML/BoxLang syntax ### Customization #### Themes You can create custom themes by extending the base theme: ```javascript const myCustomTheme = { base: 'vs-dark', inherit: true, rules: [ { token: 'keyword', foreground: 'ff0000' }, // Add your custom rules ], colors: { 'editor.background': '#1a1a1a', // Add your custom colors } }; monaco.editor.defineTheme('my-custom-theme', myCustomTheme); ``` #### Language Configuration Modify `boxlang-language-config.js` to customize: * Comment styles * Bracket pairs * Auto-closing pairs * Folding rules * Indentation rules #### Syntax Highlighting Update `boxlang-monarch-tokens.js` to add or modify: * Keywords * Operators * Token patterns * Syntax rules ### Development #### Testing Changes 1. Make your changes to the source files 2. Run `npm run dev` to start the Vite development server 3. Open to test your changes 4. The page will automatically reload when you save changes thanks to Vite's fast HMR (Hot Module Replacement) #### Adding New Keywords To add new BoxLang keywords: 1. Edit `boxlang-monarch-tokens.js` 2. Add the keyword to the `keywords` array 3. If it's a type keyword, also add it to `typeKeywords` 4. Test the highlighting in the demo ### Troubleshooting #### Common Issues **Q: Monaco Editor shows "Language 'boxlang' is not configured" error** A: Make sure you call `initializeBoxLangSupport()` before creating the editor: ```javascript import { initializeBoxLangSupport } from 'boxlang-monaco-editor'; initializeBoxLangSupport(); // Call this first // Then create your editor ``` **Q: Syntax highlighting doesn't work** A: Verify the language is set correctly when creating the editor: ```javascript const editor = monaco.editor.create(container, { value: 'your code', language: 'boxlang', // For .bx/.bxs files // OR language: 'boxlang-template' // For .bxm files }); ``` **Q: Custom theme not applied** A: Ensure the theme is set after initialization: ```javascript initializeBoxLangSupport(); monaco.editor.setTheme('boxlang-theme'); ``` **Q: TypeScript errors when importing** A: The package includes TypeScript definitions. If you encounter issues, try: ```typescript import type { BoxLangMonacoEditor } from 'boxlang-monaco-editor'; // OR import * as BoxLangMonaco from 'boxlang-monaco-editor'; ``` #### Performance Tips * Use `automaticLayout: true` for responsive editors * Consider lazy loading for large applications * Use `tokenization.colorValidation: false` for better performance with many colors ### Contributing We welcome contributions! Here's how you can help: #### Reporting Issues * Use the [GitHub issue tracker](https://github.com/ortus-boxlang/boxlang-monaco-editor/issues) * Include a clear description and steps to reproduce * Provide code samples when possible * Mention your browser and Monaco Editor version #### Development Setup 1. Fork the repository 2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/boxlang-monaco-editor.git` 3. Install dependencies: `npm install` 4. Start development server: `npm run dev` 5. Make your changes 6. Test thoroughly using the demo at `http://localhost:3000` 7. Run linting: `npm run lint` 8. Create a pull request #### Areas for Contribution * **New Language Features**: Add support for additional BoxLang syntax * **Theme Improvements**: Enhance the color scheme or add new themes * **IntelliSense**: Expand autocompletion with more BoxLang functions * **Performance**: Optimize tokenization and parsing * **Documentation**: Improve examples and API documentation * **Testing**: Add unit tests and integration tests #### Code Style * Follow the existing ESLint configuration * Use meaningful commit messages * Add JSDoc comments for new functions * Update README for new features ### License Apache 2.0 - see the LICENSE file for details. ### Related Projects * [BoxLang](https://boxlang.io) - The BoxLang programming language * [Monaco Editor](https://microsoft.github.io/monaco-editor/) - The code editor that powers VS Code * [TextMate](https://macromates.com) - The original editor supporting TextMate grammars --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://boxlang.ortusbooks.com/getting-started/ide-tooling/boxlang-monaco-editor.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.