VSCode Elements

For the end-user documentation, click here. This site is also mirrored at https://vscode-elements.netlify.app, where users behind the GFW can access it more quickly.

This documentation is intended for developers who would like to contribute to or modify the code on their own.

VSCode Elements is based on the Lit library. The local development environment requires NodeJS 22 or newer. If you want to use a local copy of the library in your codebase, you can use the npm link command. First, navigate to the VSCode Elements directory and run:

npm link

Then, go to the library where you want to use it and run:

npm link @vscode-elements/elements

[!WARNING]

Multiple packages must be linked with a single command. For example:

npm link @vscode-elements/elements @vscode-elements/webview-playground

Don't forget to run the build script before using the package.

Setup

Install dependencies:

npm ci

The scripts defined in package.json

Each script can be run using the npm run <script_name> format. Wireit is used to cache the script results.

build

Build everything. This command generates all the files that will be included in the package. These include:

• Transpiled JavaScript files with type definitions and source maps.
• The custom elements manifest file.
• VSCode custom data files.
• The entire library as a single, minified JavaScript file.

built:ts

Transpiles TypeScript files into standard ES6 JavaScript, without minification. These files can then be imported and optimized in the end-user application.

build:watch

Same as the above, but the TypeScript compiler run in watch mode and recompile the modified files automatically.

clean

Removes the generated files.

lint

Code style check with ESLint.

lint:fix

Automatically fixing code style issues.

prettier

Checks code formatting with Prettier.

prettier:fix

Automatically fixing code format issues.

analyze

Generates a custom elements manifest file. This file is shipped with the package, and it is the file on which the API view in the documentation site is based.

serve

Start the Web Test Runner development server.

start

Start the development server and the TypeScript compiler in watch mode, then opens the default browser. This is the most used command during the development.

test

Compiles the test files and runs them. Because tests are written in TypeScript, a transpilation step is also needed.

test:coverage

Same as above, but it also generates coverage.

test:watch

Watches file changes and runs the tests automatically when any modifications are detected.

wtr:watch

Starts the web-test-runner in watch mode without rebuilding any files. It can be run in a separate terminal during development, allowing you to catch new errors as you code.

checksize

Displays the file size of the bundled library (dist/bundled.js) in bytes.

icons

Generates icon list for the documentation site. The output of this script should replace the List of icons section inside the vscode-elements.github.io/src/content/docs/components/icon.mdx so the docs stay in sync with the latest Codicon set.

vscode-data

Generates HTML and CSS custom data format for VSCode code completions.