@darkobits/vsct

A tool for authoring VS Code themes in JavaScript and distributing them via NPM.

Not related to the Visual Studio Command Table file format.

Prerequisites

You should have at least a working knowledge of the JavaScript programming language and of how VS Code themes are authored. For more resources on these topics, see Additional Resources below.

This documentation also assumes you have sensibly recent versions of Node, NPM, and VS Code installed on your system.

Install

If starting a new project, you may use npm init to generate the necessary files to get you started. Then, to install VSCT, run:

npm install --save-dev @darkobits/vsct

Use

VSCT consists of two components:

1. A framework for authoring VS Code themes in JavaScript/TypeScript, the use of which is optional.
2. A CLI, responsible for compiling themes to JSON, installing themes, and providing a user-friendly development workflow.

Framework

VSCT aims to make theme authoring easier, more precise, and more reliable by giving creators the ability to write themes using a modern programming language. This allows creators to build large, complex themes leveraging the millions of amazing packages in the NPM ecosystem.

For example, VSCT ships with the powerful Color library, which lets authors work with colors in multiple color spaces, manipulate color using a straightforward API, and minimize repetition and typos.

When it's time to publish your work, VSCT makes it easy to compile your JavaScript-based themes to the JSON format that VS Code expects. You can then publish directly to NPM, and users can install your theme using npm install. Alternatively, if you have a Microsoft Azure DevOps account, you may publish to the Visual Studio Marketplace.

💡 Protip: Using the VSCT framework to define your theme is completely optional. It is mostly syntactic sugar to improve readability and promote organization. As long as a theme's default export is a serializable object that conforms to the VS Code theme spec, you are free to use any tools you want.

ThemeFactory((theme: ThemeGenerator) => void): ThemeDefinition

VSCT's default export is a function that accepts a callback that will be passed a ThemeGenerator object containing various functions for programmatically defining a VS Code theme. These functions are documented in more detail below.

The object returned by this function can be serialized into JSON using JSON.stringify, which will produce a valid VS Code theme definition.

ThemeGenerator

This section documents the API for the ThemeGenerator object passed to the ThemeFactory callback function.

tokenColors.add(value: GrammarDescriptor): void

"Token Colors" are used to highlight a document in a VS Code editor pane.

This method accepts a GrammarDescriptor object (used for syntax-highlighting) and adds the provided settings to the theme.

A GrammarDescriptor consists of an optional name, a list of scopes, and a settings object specifying how to style syntax.

💡 Protip: To help prevent errors, VSCT uses an object rather than a string for settings.fontStyle. This object may contain any combination of bold, italic, and underline properties that should map to boolean values.

Example

import ThemeFactory from '@darkobits/astra'

export default ThemeFactory(theme => {
  theme.tokenColors.add({
    name: 'Variables',
    scope: [
      'meta.definition variable',
      'variable.other.readwrite',
      'entity.quasi variable.other'
    ],
    settings: {
      foreground: '#FF0000',
      fontStyle: {
        bold: true
      }
    }
  });
});

colors.add(value: ColorSettings): void

This method is used to style the VS Code user interface. This method accepts a ColorSettings object and adds the provided settings to the theme.

A ColorSettings object is a mapping of VS Code theme color tokens to either:

• a valid color value such as #023BF3
• a Color instance

Example

import ThemeFactory, { Color } from '@darkobits/astra'

export default ThemeFactory(theme => {
  theme.colors.add({
    'editor.background': '#FF0000'
    'editor.foreground': new Color({r: 255, g: 0, b: 0})
  });
});

💡 Protip: The Color export from VSCT is a wrapper for the excellent color package with custom serialization added. Refer to the documentation for color to construct and manipulate colors, but always use the export from VSCT to ensure themes are serialized correctly.

get(path: string): any

Accepts a dot-delimited path and returns the value at that path in the theme object.

Example:

import ThemeFactory from '@darkobits/vsct';

export default ThemeFactory(theme => {
  const activityBarBg = theme.get('colors.activityBar.background');
});

set(path: string, value: any): void

Provided a dot-delimited path and a value, sets the value at the path in the theme object.

Example:

import ThemeFactory from '@darkobits/vsct';

export default ThemeFactory(theme => {
  theme.set('colors.tokenColors.0.settings.foreground', 'hotpink);
});

CLI

This section documents the VSCT CLI, the principal functions of which are:

• Read a host package's VSCT configuration file.
• Transform JavaScript modules that export serializable objects into JSON.
• Generate a spec-compliant VS Code extension manifest file.
• Create symbolic links from the VS Code extensions directory to the package's local output directory.

The VSCT CLI is intended to be used in a directory containing a package.json file – or a subdirectory thereof. The directory containing this file is considered the "root" directory of a project. A VSCT configuration file, vsct.config.js, should be created in the root directory. This file is used to provide information about your theme to the CLI.

Configuration File

VSCT tries to infer most of the information it needs to generate a manifest for your extension (also named package.json) from your project's package.json. However, where additional information is needed, a VSCT configuration file, vsct.config.js, should be used.

Below is an example VSCT configuration file with a description of each supported option.

vsct.config.js

module.exports = {
  /**
   * Override VSCT's default package.json inference (using the de-scoped "name")
   * and provide an explicit value for the extension's "name". This is also the
   * name the extension will publish to on NPM, but will not be shown to users
   * in the VS Code interface.
   */
  name: 'one-dark-pro';

  /**
   * Override VSCT's default package.json inference (reading from "displayName")
   * and provide an explicit value for the extension's "displayName". This is
   * shown in the Extensions list and in the extensions detail screen.
   */
  displayName: 'One Dark Pro',

  /**
   * Override VSCT's default package.json inference (reading from "author") and
   * provide an explicit value for the extension's "publisher".
   */
  publisher: 'binaryify',

  /**
   * Directory relative to this file where VSCT will write compiled extensions.
   *
   * Default: .vsct-extension
   */
  outDir: 'themes',

  /**
   * Array of theme descriptor objects for each theme provided by the extension.
   * Each entry's "path" field should point to a require()-able JavaScript file
   * that can be interpreted by the system's current version of Node. The
   * module's default export should be the return value of `ThemeFactory` or an
   * object that can be serialized.
   *
   * Required.
   */
  themes: [{
    /**
     * Value that will appear in the "Select Color Theme" drop-down.
     *
     * Required.
     */
    label: 'One Dark Pro',

    /**
     * One of "vs-light" or "vs-dark".
     */
    uiTheme: 'vs-dark',

    /**
     * Path relative to this file where the entrypoint for the theme can be
     * found.
     */
    path: 'dist/one-dark-pro.js'
  }]
};

vsct compile

This command will read the project's package.json and VSCT configuration file. It will then compile each theme enumerated in the configuration file's themes array, generate an extension manifest, and write each to outDir. This command will also copy files like LICENSE and README.md if present. As a result, outDir should be a valid, self-contained VS Code extension.

vsct dev

This command will create a symbolic link in the current user's VS Code extensions directory that points to the configured outDir. Assuming the extension has been compiled, it will be loaded the next time VS Code is opened or a VS Code window is reloaded.

vsct start

This command is designed for developing a VS Code theme with VSCT. It will wait for files in outDir to become present, then invoke compile and dev to install the local extension into VS Code. It will then watch outDir and continuously re-compile the extension as theme source files are changed.

💡 Protip: Unfortunately, this command cannot reload a VS Code window for you when a theme's code changes, so you'll have to reload windows manually when you make a change in order to see them reflected in the VS Code interface.

Publishing to NPM

Themes are compiled by VSCT to have zero runtime dependencies and ship with a small installer script to create a symbolic link from VS Code's extensions directory to the directory where the NPM package was installed. As such, you should not run npm publish from the root directory of the project. Rather, run npm publish .vsct-extension (or whatever your configured outDir is) to publish an extension to NPM.

To prevent accidental invocations of npm publish from the root directory, it is recommended that you add "private": true to your package.json, which will prevent NPM from accidentally publishing your entire project.

Additional Resources

• VS Code Extension Manifest Spec
• VS Code Theme Color Guide
• VS Code Syntax Highlight Guide
• TextMate Language Grammars