|
| 1 | +--- |
| 2 | +outline: deep |
| 3 | +--- |
| 4 | + |
| 5 | +# DevTools Kit |
| 6 | + |
| 7 | +> [!WARNING] |
| 8 | +> The API is still in development and may change in any version. If you are building on top of it, please mind the version of packages you are using and warn your users about the experimental status. |
| 9 | +
|
| 10 | +Vite DevTools offers a shared infrastructure for building custom DevTools for Vite and the frameworks on top of Vite. |
| 11 | + |
| 12 | +// TODO: some introduction from Anthony's Talk |
| 13 | + |
| 14 | +## DevTools Plugin |
| 15 | + |
| 16 | +Plugin/framework authors can extend the DevTools by enhancing the DevTools infrastructure with custom data visualization, actions, and more. A DevTools plugin is a **superset** of Vite plugin. |
| 17 | + |
| 18 | +To get started, in your Vite plugin project, first you need to install the `@vitejs/devtools-kit` package. Usually it's fine to be a dev dependency as we only need it for types on Node.js side. |
| 19 | + |
| 20 | +```zsh |
| 21 | +pnpm install -D @vitejs/devtools-kit |
| 22 | +``` |
| 23 | + |
| 24 | +Then referencing it in your plugin code, it will augment the `Plugin` interface with the `devtools` property. |
| 25 | + |
| 26 | +Inside `devtools.setup`, you will get tools to register custom data visualization, actions, and more. |
| 27 | + |
| 28 | +```ts {1,9-14} |
| 29 | +/// <reference types="@vitejs/devtools-kit" /> |
| 30 | +import { Plugin } from 'vite' |
| 31 | + |
| 32 | +export default function myPlugin(): Plugin { |
| 33 | + return { |
| 34 | + name: 'my-plugin', |
| 35 | + // Do other plugin stuff... |
| 36 | + transform(code, id) {}, |
| 37 | + // Devtools setup |
| 38 | + devtools: { |
| 39 | + setup(ctx) { |
| 40 | + console.log('My plugin setup') |
| 41 | + }, |
| 42 | + }, |
| 43 | + } |
| 44 | +} |
| 45 | +``` |
| 46 | + |
| 47 | +### Register A Dock Entry |
| 48 | + |
| 49 | +Dock entries are the most straight-forward entry for users to interact with your DevTools integration. Usually it will be presented as a floating panel inside user's app, or a sidebar in browser extension mode or standalone mode. "Dock" refers to macOS's Dock, where you switch between different items by clicking on them. |
| 50 | + |
| 51 | +To register a dock entry, you can use the `ctx.docks.register` method to add a new dock entry. The easiest approach is to register a iframe-based dock entry. Here we use VueUse's docs as an example: |
| 52 | + |
| 53 | +```ts {6-12} |
| 54 | +export default function VueUseDevToolsDocs(): Plugin { |
| 55 | + return { |
| 56 | + name: 'vueuse:devtools:docs', |
| 57 | + devtools: { |
| 58 | + setup(ctx) { |
| 59 | + ctx.docks.register({ |
| 60 | + id: 'vueuse:docs', |
| 61 | + title: 'VueUse', |
| 62 | + icon: 'https://vueuse.org/favicon.svg', |
| 63 | + type: 'iframe', |
| 64 | + url: 'https://vueuse.org', |
| 65 | + }) |
| 66 | + }, |
| 67 | + } |
| 68 | + } |
| 69 | +} |
| 70 | +``` |
| 71 | + |
| 72 | +The more practical usage is to build an local webpage to draw your own views and do other interactions. |
| 73 | + |
| 74 | +For example, if we hosted a local custom view at `/.my-app`, we can register it as a dock entry like this: |
| 75 | + |
| 76 | +```ts {6} |
| 77 | +ctx.docks.register({ |
| 78 | + id: 'my-app', |
| 79 | + title: 'My App', |
| 80 | + icon: 'https://my-app.com/logo.svg', |
| 81 | + type: 'iframe', |
| 82 | + url: '/.my-app', |
| 83 | +}) |
| 84 | +``` |
| 85 | + |
| 86 | +DevTools can also handles the page hosting for you, assume you have your built SPA page under `./dist/client`, you can register it as a dock entry like this: |
| 87 | + |
| 88 | +```ts {2} |
| 89 | +const pathClientDist = fileURLToPath(new URL('../dist/client', import.meta.url)) |
| 90 | +ctx.views.hostStatic('/.my-app', pathClientDist) |
| 91 | +ctx.docks.register({ |
| 92 | + id: 'my-app', |
| 93 | + title: 'My App', |
| 94 | + icon: 'https://my-app.com/logo.svg', |
| 95 | + type: 'iframe', |
| 96 | + url: '/.my-app', |
| 97 | +}) |
| 98 | +``` |
| 99 | + |
| 100 | +This way DevTools will handle the dev server middleware to host the static files for you, and also copy the static files to the dist directory when in production build. |
| 101 | + |
| 102 | +### Register An Action |
| 103 | + |
| 104 | +Instead of an iframe panel, sometime you might want to register an action button to trigger some actions to the client app. For example, you want to enable a temporary inspector tool to inspect the DOM of the client app and want to have the button on the DevTools dock. |
| 105 | + |
| 106 | +```ts {6} |
| 107 | +ctx.docks.register({ |
| 108 | + id: 'dom-inspector', |
| 109 | + title: 'DOM Inspector', |
| 110 | + type: 'action', |
| 111 | + action: { |
| 112 | + importFrom: 'vite-plugin-my-inspector/vite-devtools-action', |
| 113 | + importName: 'default', |
| 114 | + }, |
| 115 | + icon: 'ph:cursor-duotone', |
| 116 | +}) |
| 117 | +``` |
| 118 | + |
| 119 | +And in your package, you can export the sub entrypoint for the action. |
| 120 | + |
| 121 | +```ts [src/vite-devtools-action.ts] |
| 122 | +import type { DevToolsClientScriptContext } from '@vitejs/devtools-kit/client' |
| 123 | + |
| 124 | +export default function setupDevToolsAction(ctx: DevToolsClientScriptContext) { |
| 125 | + // Setup action will only execute when the entry is activated the first time |
| 126 | + |
| 127 | + // Register listeners to handle the events from the client app |
| 128 | + ctx.current.events.on('entry:activated', () => { |
| 129 | + alert('DOM inspector started! ') |
| 130 | + }) |
| 131 | +} |
| 132 | +``` |
| 133 | + |
| 134 | +And in your package.json, you can export the sub entrypoint: |
| 135 | + |
| 136 | +```json [package.json] |
| 137 | +{ |
| 138 | + "name": "vite-plugin-my-inspector", |
| 139 | + "exports": { |
| 140 | + "./vite-devtools-action": "./dist/vite-devtools-action.mjs" |
| 141 | + } |
| 142 | +} |
| 143 | +``` |
| 144 | + |
| 145 | +That's it! When users install your plugin, they can use your action button in the dock, and when the entry is activated the first time, the action will be executed in the user's app for you to handle the logic. |
| 146 | + |
| 147 | +## References |
| 148 | + |
| 149 | +The docs might not cover all the details, please help us to improve it by submitting PRs. And in the meantime, you can refer to the following existing DevTools integrations for reference (but note they might not always be up to date with the latest API changes): |
| 150 | + |
| 151 | +- [UnoCSS Inspector](https://github.com/unocss/unocss/blob/25c0dd737132dc20b257c276ee2bc3ccc05e2974/packages-integrations/inspector/src/index.ts#L140-L150) (a simple iframe-based dock entry) |
| 152 | +- `vite-plugin-vue-tracer` (a simple action button to trigger the DOM inspector) |
| 153 | + - [plugin hook](https://github.com/antfu/vite-plugin-vue-tracer/blob/9f86fe723543405eea5d30588fe783796193bfd8/src/plugin.ts#L139-L157) |
| 154 | + - [client script](https://github.com/antfu/vite-plugin-vue-tracer/blob/main/src/client/vite-devtools.ts) |
0 commit comments