Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tomjs/vite-plugin-vscode
用 vue/react 来开发 vscode extension webview ,支持 esm 和 cjs。Use vue/react to develop vscode extension webview, supporting esm and cjs.
https://github.com/tomjs/vite-plugin-vscode
extension hmr hot plugin react vite vscode vue webview
Last synced: 6 days ago
JSON representation
用 vue/react 来开发 vscode extension webview ,支持 esm 和 cjs。Use vue/react to develop vscode extension webview, supporting esm and cjs.
- Host: GitHub
- URL: https://github.com/tomjs/vite-plugin-vscode
- Owner: tomjs
- License: mit
- Created: 2023-12-19T14:56:51.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-12-06T13:23:05.000Z (about 2 months ago)
- Last Synced: 2025-01-07T21:07:37.455Z (13 days ago)
- Topics: extension, hmr, hot, plugin, react, vite, vscode, vue, webview
- Language: TypeScript
- Homepage:
- Size: 457 KB
- Stars: 48
- Watchers: 2
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- fucking-awesome-vite - @tomjs/vite-plugin-vscode - Easily use web frameworks to develop `VSCode Extension`'s `Webview`, and support `HMR` and `Debug`. (Plugins / Framework-agnostic Plugins)
- awesome-vite - @tomjs/vite-plugin-vscode - Easily use web frameworks to develop `VSCode Extension`'s `Webview`, and support `HMR` and `Debug`. (Plugins / Framework-agnostic Plugins)
README
# @tomjs/vite-plugin-vscode
[![npm](https://img.shields.io/npm/v/@tomjs/vite-plugin-vscode)](https://www.npmjs.com/package/@tomjs/vite-plugin-vscode) ![node-current (scoped)](https://img.shields.io/node/v/@tomjs/vite-plugin-vscode) ![NPM](https://img.shields.io/npm/l/@tomjs/vite-plugin-vscode) [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@tomjs/vite-plugin-vscode)
**English** | [中文](./README.zh_CN.md)
> Use `vue`/`react` to develop [vscode extension webview](https://code.visualstudio.com/api/references/vscode-api#WebviewPanel), supporting `esm` and `cjs`.
In development mode, inject the same code of [@tomjs/vscode-extension-webview](https://github.com/tomjs/vscode-extension-webview) into `vscode extension code` and `web page code`, use To support `HMR`; during production build, the final generated `index.html` code is injected into `vscode extension code` to reduce the workload.
## Features
- Use [tsup](https://github.com/egoist/tsup) to quickly build `extension code`
- Simple configuration, focus on business
- Support `esm` and `cjs`
- Support webview `HMR`
- Support `acquireVsCodeApi` of [@types/vscode-webview](https://www.npmjs.com/package/@types/vscode-webview)
- Support [Multi-Page App](https://vitejs.dev/guide/build.html#multi-page-app)
- Supports `vue` and `react` and other [frameworks](https://cn.vitejs.dev/guide/#trying-vite-online) supported by `vite`## Install
```bash
# pnpm
pnpm add @tomjs/vite-plugin-vscode -D# yarn
yarn add @tomjs/vite-plugin-vscode -D# npm
npm i @tomjs/vite-plugin-vscode -D
```## Usage
### Recommended
Setting `recommended` will modify some preset configurations. See [PluginOptions](#pluginoptions) and `recommended` parameter descriptions in detail.
#### Directory Structure
- By default, `recommended:true` will be based on the following directory structure as a convention.
```
|--extension // extension code
| |--index.ts
|--src // front-end code
| |--App.vue
| |--main.ts
|--index.html
```- Zero configuration, default dist output directory
```
|--dist
| |--extension
| | |--index.js
| | |--index.js.map
| |--webview
| | |--index.html
```- If you want to modify the `extension` source code directory to `src`, you can set `{ extension: { entry: 'src/index.ts' } }`
```
|--src // extension code
| |--index.ts
|--webview // front-end code
| |--App.vue
| |--main.ts
|--index.html
```### extension
code snippet, more code see examples
```ts
const panel = window.createWebviewPanel('showHelloWorld', 'Hello World', ViewColumn.One, {
enableScripts: true,
localResourceRoots: [Uri.joinPath(extensionUri, 'dist/webview')],
});// Vite development mode and production mode inject different webview codes to reduce development work
panel.webview.html = process.env.VITE_DEV_SERVER_URL
? __getWebviewHtml__(process.env.VITE_DEV_SERVER_URL)
: __getWebviewHtml__(webview, context);
```- `package.json`
```json
{
"main": "dist/extension/index.js"
}
```### vue
- `vite.config.ts`
```ts
import { defineConfig } from 'vite';
import vscode from '@tomjs/vite-plugin-vscode';
import vue from '@vitejs/plugin-vue';// https://vitejs.dev/config/
export default defineConfig({
plugins: [
vue({
template: {
compilerOptions: {
isCustomElement: (tag: string) => tag.startsWith('vscode-'),
},
},
}),
vscode(),
// Modify the extension source code entry path, and also modify the `index.html` entry file path
// vscode({ extension: { entry: 'src/index.ts' } }),
],
});
```### react
- `vite.config.ts`
```ts
import { defineConfig } from 'vite';
import vscode from '@tomjs/vite-plugin-vscode';
import react from '@vitejs/plugin-react-swc';// https://vitejs.dev/config/
export default defineConfig({
plugins: [react(), vscode()],
});
```### Multi-page application
See [vue-import](./examples/vue-import) example
- `vite.config.ts`
```ts
import path from 'node:path';
import vscode from '@tomjs/vite-plugin-vscode';export default defineConfig({
build: {
plugins: [vscode()]
rollupOptions: {
// https://cn.vitejs.dev/guide/build.html#multi-page-app
input: [path.resolve(__dirname, 'index.html'), path.resolve(__dirname, 'index2.html')],
// You can also customize the name
// input:{
// 'index': path.resolve(__dirname, 'index.html'),
// 'index2': path.resolve(__dirname, 'index2.html'),
// }
},
},
});
```- page one
```ts
process.env.VITE_DEV_SERVER_URL
? __getWebviewHtml__(process.env.VITE_DEV_SERVER_URL)
: __getWebviewHtml__(webview, context);
```- page two
```ts
process.env.VITE_DEV_SERVER_URL
? __getWebviewHtml__(`${process.env.VITE_DEV_SERVER_URL}/index2.html`)
: __getWebviewHtml__(webview, context, 'index2');
```**getWebviewHtml** Description
```ts
/**
* `[vite serve]` Gets the html of webview in development mode.
* @param options serverUrl: The url of the vite dev server.
*/
function __getWebviewHtml__(options?: string | { serverUrl: string }): string;/**
* `[vite build]` Gets the html of webview in production mode.
* @param webview The WebviewPanel instance of the extension.
* @param context The ExtensionContext instance of the extension.
* @param inputName vite build.rollupOptions.input name. Default is `index`.
*/
function __getWebviewHtml__(
webview: Webview,
context: ExtensionContext,
inputName?: string,
): string;
```### Warning
When using the `acquireVsCodeApi().getState()` method of [@types/vscode-webview](https://www.npmjs.com/package/@types/vscode-webview), you must use `await` to call it. Since `acquireVsCodeApi` is a simulated implementation of this method by the plugin, it is inconsistent with the original method. I am very sorry. If you have other solutions, please share them. Thank you very much.
```ts
const value = await acquireVsCodeApi().getState();
```## Documentation
- [index.d.ts](https://www.unpkg.com/browse/@tomjs/vite-plugin-vscode/dist/index.d.ts) provided by [unpkg.com](https://www.unpkg.com).
## Parameters
### PluginOptions
| Property | Type | Default | Description |
| --- | --- | --- | --- |
| recommended | `boolean` | `true` | This option is intended to provide recommended default parameters and behavior. |
| extension | [ExtensionOptions](#ExtensionOptions) | | Configuration options for the vscode extension. |
| webview | `boolean` \| `string` \| [WebviewOption](#WebviewOption) | `__getWebviewHtml__` | Inject html code |
| devtools | `boolean` | `true` | Inject script code for [react-devtools](https://github.com/facebook/react/tree/main/packages/react-devtools) or [vue-devtools](https://devtools.vuejs.org/guide/standalone) debugging |#### Notice
The `recommended` option is used to set the default configuration and behavior, which can be used with almost zero configuration. The default is `true`. If you want to customize the configuration, set it to `false`. The following default prerequisites are to use the recommended [project structure](#directory-structure).
- The output directory is based on the `build.outDir` parameter of `vite`, and outputs `extension` and `src` to `dist/extension` and `dist/webview` respectively.
- Other behaviors to be implemented#### Webview
Inject [@tomjs/vscode-extension-webview](https://github.com/tomjs/vscode-extension-webview) into vscode extension code and web client code, so that `webview` can support `HMR` during the development stage.
- vite serve
- extension: Inject `import __getWebviewHtml__ from '@tomjs/vite-plugin-vscode/webview';` at the top of the file that calls the `__getWebviewHtml__` method
- web: Add `` tag to index.html and inject `@tomjs/vite-plugin-vscode/client` code
- vite build
- extension: Inject `import __getWebviewHtml__ from '@tomjs/vite-plugin-vscode-inject';` at the top of the file that calls the `__getWebviewHtml__` methodIf is string, will set inject method name. Default is `__getWebviewHtml__`.
#### devtools
During development, support standalone development tool applications for `react` and `vue`, enabled by default.
- `react`: inject `<script src="http://localhost:8097">`, support [react-devtools](https://github.com/facebook/react/tree/main/packages/react-devtools)
- `vue`: inject ``, support [vue-devtools](https://devtools.vuejs.org/guide/standalone)### ExtensionOptions
Based on [Options](https://paka.dev/npm/tsup) of [tsup](https://tsup.egoist.dev/), some default values are added for ease of use.
| Property | Type | Default | Description |
| --- | --- | --- | --- |
| entry | `string` | `extension/index.ts` | The vscode extension entry file. |
| outDir | `string` | `dist-extension/main` | The output directory for the vscode extension file |
| onSuccess | `() => Promise void \| Promise)>` | `undefined` | A function that will be executed after the build succeeds. |### WebviewOption
| Property | Type | Default | Description |
| --- | --- | --- | --- |
| name | `string` | `__getWebviewHtml__` | The inject method name |
| csp | `string` | `` | The `CSP` meta for the webview |- `{{cspSource}}`: [webview.cspSource](https://code.visualstudio.com/api/references/vscode-api#Webview)
- `{{nonce}}`: uuid### Additional Information
- Default values for `extension` when the relevant parameters are not configured
| Parameter | Development Mode Default | Production Mode Default |
| --------- | ------------------------ | ----------------------- |
| sourcemap | `true` | `false` |
| minify | `false` | `true` |## Environment Variables
### Vite plugin variables
`vscode extension` use.
- `development` mode
| Variable | Description |
| --------------------- | ------------------------------ |
| `VITE_DEV_SERVER_URL` | The url of the vite dev server |- `production` mode
| Variable | Description |
| ------------------- | ----------------------------- |
| `VITE_WEBVIEW_DIST` | vite webview page output path |## Debug
Run `Debug Extension` through `vscode` to debug. For debugging tools, refer to [Official Documentation](https://code.visualstudio.com/docs/editor/debugging)
`launch.json` is configured as follows:
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug Extension",
"type": "extensionHost",
"request": "launch",
"args": ["--extensionDevelopmentPath=${workspaceFolder}"],
"outFiles": ["${workspaceFolder}/dist/extension/*.js"],
"preLaunchTask": "npm: dev"
},
{
"name": "Preview Extension",
"type": "extensionHost",
"request": "launch",
"args": ["--extensionDevelopmentPath=${workspaceFolder}"],
"outFiles": ["${workspaceFolder}/dist/extension/*.js"],
"preLaunchTask": "npm: build"
}
]
}
````tasks.json` is configured as follows:
```json
{
"version": "2.0.0",
"tasks": [
{
"type": "npm",
"script": "dev",
"problemMatcher": {
"owner": "typescript",
"fileLocation": "relative",
"pattern": {
"regexp": "^([a-zA-Z]\\:/?([\\w\\-]/?)+\\.\\w+):(\\d+):(\\d+): (ERROR|WARNING)\\: (.*)$",
"file": 1,
"line": 3,
"column": 4,
"code": 5,
"message": 6
},
"background": {
"activeOnStart": true,
"beginsPattern": "^.*extension build start*$",
"endsPattern": "^.*extension (build|rebuild) success.*$"
}
},
"isBackground": true,
"presentation": {
"reveal": "never"
},
"group": {
"kind": "build",
"isDefault": true
}
},
{
"type": "npm",
"script": "build",
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": []
}
]
}
```## Examples
First execute the following command to install dependencies and generate library files:
```bash
pnpm install
pnpm build
```Open the [examples](./examples) directory, there are `vue` and `react` examples.
- [react](./examples/react): Simple react example.
- [vue](./examples/vue): Simple vue example.
- [vue-import](./examples/vue-import): Dynamic import() and multi-page examples.## Related
- [@tomjs/vscode](https://npmjs.com/package/@tomjs/vscode): Some utilities to simplify the development of [VSCode Extensions](https://marketplace.visualstudio.com/VSCode).
- [@tomjs/vscode-dev](https://npmjs.com/package/@tomjs/vscode-dev): Some development tools to simplify the development of [vscode extensions](https://marketplace.visualstudio.com/VSCode).
- [@tomjs/vscode-webview](https://npmjs.com/package/@tomjs/vscode-webview): Optimize the `postMessage` issue between `webview` page and [vscode extensions](https://marketplace.visualstudio.com/VSCode)## Important Notes
### v3.0.0
**Breaking Updates:**
- The simulated `acquireVsCodeApi` is consistent with the `acquireVsCodeApi` of [@types/vscode-webview](https://www.npmjs.com/package/@types/vscode-webview), and `sessionStorage.getItem` and `sessionStorage.setItem` are used to implement `getState` and `setState`.