Visual Studio Code extension helpers

The @estruyf/vscode package contains a couple of helpers to make Visual Studio Code Extension development easier.

Installation

Using npm

``bash
npm i @estruyf/vscode
`

Helpers

$3

Configuration helpers to make it easier to fetch a setting of your extension.

`typescript
import { Configuration } from "@estruyf/vscode";

const config = Configuration.get("section");

const mdConfig = Configuration.getForLanguage("markdown");

const setting = Configuration.getSetting("section", "setting");

await Configuration.updateSetting("section", "setting", value);

await Configuration.updateSettingForLanguage(
"markdown",
"setting",
value
);
`

$3

`typescript
import { EditorHelper } from "@estruyf/vscode";

// Show a file in the editor
EditorHelper.showFile(filepath);

// Read a file's content
const content = await EditorHelper.readFile(uri);

// Write content to a file
await EditorHelper.writeFile(uri, "Hello World");

// Check if a file exists
const exists = await EditorHelper.fileExists(uri);
`

$3

#### Message handler

The messageHandler is a helper that makes it easier to send and request data from your extension. It is based on the postMessage and onDidReceiveMessage, but allows you to use async/await to send and receive data.

The messageHandler is can send two types of messages to the extension:

1. messageHandler.send: This is a one-way message, where you send data to the extension, but don't expect a response.
2. messageHandler.request: This is a two-way message, where you send data to the extension, and expect a response.

All you need to do to use it, is the following:

Webview

`typescript
import { messageHandler } from "@estruyf/vscode/dist/client";

// Sends a message with id: "GET_DATA"
messageHandler.request("GET_DATA").then((data: any) => {
// Do something with the returned data
console.log(data);
});

// Sends a message with id: "POST_DATA" - no data is expected back
messageHandler.send("POST_DATA", { dummy: "Nothing to report..." });
`

Extension

`typescript
import { MessageHandlerData } from "@estruyf/vscode";

panel.webview.onDidReceiveMessage(
(message) => {
const { command, requestId, payload } = message;

if (command === "GET_DATA") {
// Do something with the payload

// Send a response back to the webview
panel.webview.postMessage({
command,
requestId, // The requestId is used to identify the response
payload: Hello from the extension!,
} as MessageHandlerData);
} else if (command === "POST_DATA") {
// Do something with the payload
}
},
undefined,
context.subscriptions
);
`

##### Errors

In case you want to send an error back to the webview, you can use the error property instead of the payload property and pass in your error data.

Extension

`typescript
panel.webview.postMessage({
command,
requestId, // The requestId is used to identify the response
error: Something went wrong!,
} as MessageHandlerData);
`

Webview

`typescript
messageHandler
.request("GET_DATA_ERROR")
.then((msg) => {
setMessage(msg);
})
.catch((err) => {
setError(err);
});
`

#### Messenger

The messenger can be used to send messages to your extension or listen to messages coming from your extension.

`typescript
import { Messenger } from "@estruyf/vscode/dist/client";

// Get the VS Code API in your webview
Messenger.getVsCodeAPI();

// Listen to messages from your extension.
const listener = (message: MessageEvent>) => {
const event = message.data;
console.log(event.command, event.payload);
};

Messenger.listen(listener);

// Remove a listener
Messenger.unlisten(listener);

// Send a message to your extension
Messenger.send("command", payload);
`

#### WebviewHelper

`typescript
import { WebviewHelper } from "@estruyf/vscode";

// Generate a random string for your webview
WebviewHelper.getNonce();
`

$3

#### Theme Utilities

`typescript
import { getThemes, getTheme } from "@estruyf/vscode";

// Get all contributed themes
const themes = getThemes();

// Get the currently active theme or a specific theme by name
const theme = await getTheme();
const specificTheme = await getTheme("Dark+ (default dark)");
`

#### Path Utilities

`typescript
import { parseWinPath } from "@estruyf/vscode";

// Convert Windows path to POSIX path
const posixPath = parseWinPath("C:\\Users\\Name\\file.txt"); // "C:/Users/Name/file.txt"
`

#### Workspace Utilities

`typescript
import { bringToFront } from "@estruyf/vscode";
import { Uri } from "vscode";

// Bring a workspace folder to the front in VS Code
await bringToFront(Uri.file("/path/to/workspace"));
`

$3

#### ExtensionInfo

The ExtensionInfo class provides metadata and state management for your extension.

`typescript
import { ExtensionInfo } from "@estruyf/vscode";

const extInfo = ExtensionInfo.getInstance(context);
const name = extInfo.name;
const version = extInfo.version;
const isUpdated = extInfo.isUpdated();
extInfo.updateVersion();
`

$3

#### TeamSettings

The TeamSettings class helps manage team-based configuration files and settings.

`typescript
import { TeamSettings } from "@estruyf/vscode";

// Initialize team settings
TeamSettings.init("team-settings.json", "myExtension");

// Get a team setting
const value = TeamSettings.get("settingKey");

// Update a team setting
await TeamSettings.update("settingKey", "newValue");

// Listen for config changes
TeamSettings.onConfigChange((global) => {
// Handle config change
});
``

License

MIT License