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:

``bash
npm link
`

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

`bash
npm link @vscode-elements/elements
`

> [!WARNING]
>
> Multiple packages must be linked with a single command. For example:
>
> `bash
> npm link @vscode-elements/elements @vscode-elements/webview-playground
> `

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

Setup

Install dependencies:

`bash
npm ci
`

The scripts defined in package.json

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

$3

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.

$3

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

$3

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

$3

Removes the generated files.

$3

Code style check with ESLint.

$3

Automatically fixing code style issues.

$3

Checks code formatting with Prettier.

$3

Automatically fixing code format issues.

$3

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.

$3

Start the Web Test Runner development server.

$3

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.

$3

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

$3

Same as above, but it also generates coverage.

$3

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

$3

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.

$3

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

$3

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.

$3

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