DOCSEARCHbyAlgolia
Submit Docs

monaco-themes

repository·master·Indexed 19 days ago

https://github.com/brijeshb42/monaco-themes

A collection of theme definitions and utilities for integrating color themes into the Monaco Editor in web browsers. It includes the parseTmTheme() function to convert TextMate (.tmTheme) files into Monaco-compatible JSON objects, handling base detection, color normalization, and scope mapping. The library supports ESM, CommonJS, and IIFE build formats for use with modern bundlers or direct <script> tag integration.

Tokens
2.2K
Snippets
10
Records
10
Agent score
66%

What's inside monaco-themes

  2. Import themes directly with modern bundlers

    master

    If you are using Vite, Webpack, or similar bundlers, you can import the pre-generated JSON theme files directly from the monaco-themes/themes/ path.

    const monaco =
  /* import monaco */

  import('monaco-themes/themes/Monokai.json').then((data) => {
    monaco.editor.defineTheme('monokai', data.default || data);
    monaco.editor.setTheme('monokai');
  });

  3. Load themes via fetch

    master

    You can host the themes directory from this repository in your own project and load the JSON files using the standard fetch API.

    /* load monaco */

fetch('/themes/Monokai.json')
  .then((data) => data.json())
  .then((data) => {
    monaco.editor.defineTheme('monokai', data);
    monaco.editor.setTheme('monokai');
  });

  4. Use monaco-themes via <script> tag (IIFE/UMD)

    master

    For direct browser usage without a bundler, include the library via unpkg. The library is exposed under the global MonacoThemes object.

    <script
  type="text/javascript"
  src="https://unpkg.com/monaco-themes/dist/monaco-themes.js"
></script>
<script type="text/javascript">
  var tmThemeString = /* read using FileReader */
  var themeData = MonacoThemes.parseTmTheme(tmThemeString);
  monaco.editor.defineTheme('mytheme', themeData);
  monaco.editor.setTheme('mytheme');
</script>

  5. Use monaco-themes via CommonJS

    master

    If your environment does not support ESM, you can use the CommonJS pattern to import parseTmTheme.

    const { parseTmTheme } = require('monaco-themes');

const tmThemeString = /* read using FileReader */
const themeData = parseTmTheme(tmThemeString);
monaco.editor.defineTheme('mytheme', themeData);
monaco.editor.setTheme('mytheme');

  6. Parse TextMate themes using parseTmTheme()

    master

    The parseTmTheme function converts a TextMate theme string into a JSON object compatible with monaco.editor.defineTheme. This is the recommended way to transform raw theme files into Monaco-compatible formats.

    import { parseTmTheme } from 'monaco-themes';

const tmThemeString = /* read using FileReader */
const themeData = parseTmTheme(tmThemeString);
monaco.editor.defineTheme('mytheme', themeData);
monaco.editor.setTheme('mytheme');

  7. Configure tsdown for monaco-themes builds

    master

    The monaco-themes project uses tsdown to generate multiple build formats (ESM, CJS, and IIFE). The configuration defines a commonConfig object applied to all builds, which includes settings for cleaning the output directory, generating sourcemaps, targeting the browser platform, and enabling tree-shaking. It also injects a license banner into the generated JavaScript files using metadata from package.json.

    import { defineConfig, type UserConfig } from 'tsdown';

const commonConfig: UserConfig = {
  clean: true,
  sourcemap: true,
  platform: 'browser',
  treeshake: true,
  skipNodeModulesBundle: true,
  env: {
    NODE_ENV: 'production',
  },
  banner: {
    js: `/**
 * monaco-themes v0.4.8
  * (c) 2026 Brijesh
  * @license MIT
 */`
  }
};

  8. Convert TextMate themes using parseTmTheme()

    master

    The parseTmTheme function converts a raw TextMate (.tmTheme) file string into a MonacoTheme object compatible with the Monaco Editor API. It parses the Property List (plist) content, maps TextMate scopes to Monaco rules, and translates global color settings (like foreground, background, and selection) into Monaco's color configuration format.

    Key behaviors:

    • Base Detection: Automatically determines if the theme should use the vs-dark or vs base by analyzing the darkness of the editor.background color.
    • Color Normalization: Handles various color formats (hex, RGB) and maps TextMate keys (e.g., foreground, selection) to Monaco keys (e.g., editor.foreground, editor.selectionBackground).
    • Scope Mapping: Splits comma-separated scope strings into individual Monaco rules.

    Refer to the Monaco Editor documentation for the expected structure of the returned object.

    import { parseTmTheme } from 'monaco-themes';

const rawTmThemeString = `... contents of a .tmTheme file ...`;
const monacoTheme = parseTmTheme(rawTmThemeString);

// Use the resulting object with Monaco Editor
// monaco.editor.defineTheme('myTheme', monacoTheme);

  9. Build formats for monaco-themes

    master

    The project produces three distinct build targets via tsdown:

    1. ESM & CJS: Targeted at module bundlers. The entry point is src/index.ts and it generates TypeScript declaration files (dts: true).
    2. IIFE: Targeted at direct browser usage via <script> tags. The entry point is src/index.ts, the output filename is monaco-themes, and it exposes a global variable named MonacoThemes. This build does not generate declaration files (dts: false).

    For the IIFE build, external dependencies like fast-plist are mapped to the global FastPlist.

    export default defineConfig([
  // ESM/CJS build
  {
    entry: { index: 'src/index.ts' },
    format: ['esm', 'cjs'],
    dts: true,
  },
  // IIFE build
  {
    entry: { 'monaco-themes': 'src/index.ts' },
    globalName: 'MonacoThemes',
    format: 'iife',
    dts: false,
    outputOptions: {
      globals: {
        'fast-plist': 'FastPlist',
      },
    },
  },
]);

  10. The MonacoTheme interface

    master

    The MonacoTheme interface defines the structure required by the Monaco Editor to apply a custom theme. This interface is the output of parseTmTheme.

    PropertyTypeDescription
    base'vs-dark' | 'vs'The base theme to inherit from.
    inheritbooleanWhether to inherit from the base theme.
    rulesArray<{ token: string; foreground?: string; background?: string; fontStyle?: string; }>An array of token rules mapping scopes to styles.
    colorsRecord<string, string>A dictionary of editor UI colors (e.g., editor.background).
    export interface MonacoTheme {
  base: 'vs-dark' | 'vs';
  inherit: boolean;
  rules: {
    token: string;
    foreground?: string;
    background?: string;
    fontStyle?: string;
  }[];
  colors: Record<string, string>;
}