diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 529fb459..d8eec9be 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -15,6 +15,7 @@ const DevToolsKitNav = [ { text: 'RPC', link: '/kit/rpc' }, { text: 'Shared State', link: '/kit/shared-state' }, { text: 'Logs & Notifications', link: '/kit/logs' }, + { text: 'Examples', link: '/kit/examples' }, ] const SocialLinks = [ @@ -68,6 +69,7 @@ export default extendConfig(withMermaid(defineConfig({ { text: 'RPC', link: '/kit/rpc' }, { text: 'Shared State', link: '/kit/shared-state' }, { text: 'Logs', link: '/kit/logs' }, + { text: 'Examples', link: '/kit/examples' }, ], }, ], diff --git a/docs/kit/dock-system.md b/docs/kit/dock-system.md index 719ec987..e4b4d8db 100644 --- a/docs/kit/dock-system.md +++ b/docs/kit/dock-system.md @@ -109,6 +109,9 @@ icon: 'mdi:view-dashboard' // Material Design Icons > [!TIP] > Browse available icons at [Iconify](https://icon-sets.iconify.design/). The `ph:` (Phosphor) icon set works well for DevTools UIs. +> [!TIP] +> See the [File Explorer example](/kit/examples#file-explorer) for a iframe dock plugin with RPC and static build support. + ## Action Buttons Action buttons run client-side scripts when clicked. They're perfect for: @@ -196,6 +199,9 @@ Export the action script from your package: | `entry:activated` | Fired when the user clicks/activates this dock entry | | `entry:deactivated` | Fired when another entry is selected or the dock is closed | +> [!TIP] +> See the [A11y Checker example](/kit/examples#a11y-checker) for a real-world action dock that runs axe-core audits and reports violations as logs. + ## Custom Renderers Custom renderers let you render directly into the DevTools panel DOM. This gives you full control and is useful when: diff --git a/docs/kit/examples.md b/docs/kit/examples.md new file mode 100644 index 00000000..432e7c45 --- /dev/null +++ b/docs/kit/examples.md @@ -0,0 +1,34 @@ +--- +outline: deep +--- + +# Examples + +A collection of example plugins built with `@vitejs/devtools-kit` that demonstrate different features and patterns. + +## A11y Checker + +An accessibility auditing plugin powered by [axe-core](https://github.com/dequelabs/axe-core). + +**Features demonstrated:** + +- Registering an `action` dock entry with a client-side script +- Running axe-core accessibility audits on the current page +- Reporting violations as DevTools logs with severity levels +- Using log handles to update a summary log in-place + +**Source:** [`examples/plugin-a11y-checker`](https://github.com/vitejs/devtools/tree/main/examples/plugin-a11y-checker) + +## File Explorer + +A file explorer dock that lists, reads, and writes files through RPC. + +**Features demonstrated:** + +- Creating and registering RPC functions (`static`, `query`, `action`) +- Hosting a custom UI panel with `context.views.hostStatic(...)` +- Registering an `iframe` dock entry +- RPC dump support for static builds +- Detecting backend mode (`websocket` vs `static`) on the client + +**Source:** [`examples/plugin-file-explorer`](https://github.com/vitejs/devtools/tree/main/examples/plugin-file-explorer) diff --git a/docs/kit/logs.md b/docs/kit/logs.md index 964532fb..42e86de0 100644 --- a/docs/kit/logs.md +++ b/docs/kit/logs.md @@ -163,6 +163,9 @@ context.logs.clear() Logs have a maximum capacity of 1000 entries. When the limit is reached, the oldest entries are automatically removed. +> [!TIP] +> See the [A11y Checker example](/kit/examples#a11y-checker) for a plugin that uses logs to report accessibility violations with severity levels, element positions, and WCAG labels. + ## Dock Badge The Logs dock icon automatically shows a badge with the total log count. The icon is hidden when there are no logs. diff --git a/docs/kit/rpc.md b/docs/kit/rpc.md index 6c1f1a5e..0c384547 100644 --- a/docs/kit/rpc.md +++ b/docs/kit/rpc.md @@ -315,6 +315,9 @@ export const readFile = defineRpcFunction({ }) ``` +> [!TIP] +> See the [File Explorer example](/kit/examples#file-explorer) for a plugin using RPC functions with dump support, organized following the conventions above. + ## Schema Validation (Optional) The RPC system has built-in support for runtime schema validation using [Valibot](https://valibot.dev). When you provide schemas, TypeScript types are automatically inferred and validation happens at runtime. diff --git a/examples/plugin-a11y-checker/README.md b/examples/plugin-a11y-checker/README.md new file mode 100644 index 00000000..8e17652d --- /dev/null +++ b/examples/plugin-a11y-checker/README.md @@ -0,0 +1,27 @@ +# Example: DevTools Kit A11y Checker Plugin + +This example shows how to build an accessibility auditing plugin with `@vitejs/devtools-kit` and [axe-core](https://github.com/dequelabs/axe-core). + +It registers an **action dock** that runs an axe-core audit on the current page and reports violations as DevTools logs. + +## How It Works + +1. Node plugin (`src/node/plugin.ts`) + - registers an `action` dock entry that points to a client-side script + - sends a startup log via `context.logs.add(...)` + +2. Client script (`src/client/run-axe.ts`) + - runs `axe.run(document)` when the dock action is triggered + - maps each violation to a DevTools log with level based on impact (`critical`/`serious` → error, `moderate` → warn, `minor` → info) + - attaches WCAG tags and element selectors to each log entry + - updates a summary log with the total violation/pass count + +## Run The Example + +From the `examples/plugin-a11y-checker` directory (`cd examples/plugin-a11y-checker`): + +```bash +pnpm play:dev +``` + +Then open the app URL, open Vite DevTools, and click the **Run A11y Check** action.