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.

Documentation

Details of the changes made in this repository are documented in the docs directory. For all other documentation, visit https://vscode-elements.github.io/.

• Form control sizes explains the shared small, medium, and large sizes, supported components, runtime usage, form groups, and icon sizing.
• Multi-select face labels explains the abbreviation of vscode-option, the display priority of the vscode-multi-select face, and the collapsing and tooltip behaviour.
• Textfield percentage mode explains the percentage property of vscode-textfield, the displayed percent sign, the fraction form of the value, and the editing and validation behaviour.
• Modified state of a form explains the highlight of vscode-form-container, its duration, the form controls which take part, and the colors of the themes.

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 nusys-ui

Warning

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

npm link nusys-ui @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.

release

Run npm run release from a clean working tree. The default version increment is patch; use npm run release -- minor, npm run release -- major, or npm run release -- 3.1.0 to suggest a different version. The command prompts for the final v-prefixed version tag and confirmation.

For a new version, the command updates package.json, package-lock.json, and the component version, generates a CHANGELOG.md entry from Git commits since the previous release, then commits those files and creates the tag. Selecting the current version only creates or updates its tag and keeps its existing changelog.

Confirming the push sends the branch and tag to origin and automatically starts the GitHub Actions Release workflow. It builds, tests, and publishes nusys-ui to npmjs, then creates a GitHub release with notes from CHANGELOG.md. Check the workflow run for completion; a successful local push does not mean npm publishing has finished. If you decline the push, the command prints how to push later.

Configure a repository Actions secret named NPM_TOKEN with permission to publish nusys-ui (and bypass 2FA for unattended publishing). The workflow supplies it as NODE_AUTH_TOKEN to npm through actions/setup-node. GitHub secrets stay in Actions; the local command needs Git push access but does not need an npm token. The package repository URL must match this repository for npm provenance.

The updated workflow must be included in the commit being tagged. To retry a failed release, manually run Release in GitHub Actions and set version_tag to the existing tag. An already published npm version is skipped; publish a newer version to distribute changed package contents.