0
# Vite Plugin
1

2
The @vitest/ui Vite plugin provides a development-time web interface for Vitest, serving the UI application and handling WebSocket connections for real-time test monitoring.
3

4
## Core Import
5

6
```typescript
7
import vitestUI from "@vitest/ui";
8
```
9

10
## API
11

12
### Plugin Factory Function
13

14
Creates a Vite plugin that integrates the Vitest UI into your development server.
15

16
```typescript { .api }
17
declare function vitestUI(ctx: Vitest): Plugin;
18
```
19

20
**Parameters:**
21
- `ctx: Vitest` - The Vitest instance context containing configuration and state
22

23
**Returns:**
24
- `Plugin` - A Vite plugin object with server middleware configuration
25

26
## Usage Examples
27

28
### Basic Setup
29

30
```typescript
31
import { defineConfig } from 'vite';
32
import vitestUI from '@vitest/ui';
33

34
export default defineConfig({
35
  plugins: [
36
    vitestUI(vitestContext), // Pass your Vitest instance
37
  ],
38
});
39
```
40

41
### With Vitest Configuration
42

43
```typescript
44
import { defineConfig } from 'vitest/config';
45

46
export default defineConfig({
47
  plugins: [
48
    // Vitest will automatically configure the UI plugin when ui: true
49
  ],
50
  test: {
51
    ui: true,
52
    uiBase: '/vitest-ui', // Custom base path
53
  },
54
});
55
```
56

57
## Plugin Behavior
58

59
The plugin performs several key functions:
60

61
1. **Version Validation**: Ensures @vitest/ui version matches the Vitest core version
62
2. **Static File Serving**: Serves the Vue.js client application from the built dist directory
63
3. **Coverage Integration**: Provides access to HTML coverage reports if enabled
64
4. **File Attachment Handling**: Manages test attachments and makes them accessible via HTTP
65
5. **API Token Injection**: Injects WebSocket API tokens into the HTML for secure connections
66

67
## Middleware Configuration
68

69
The plugin configures several middleware handlers:
70

71
- **Attachment Middleware**: Serves test attachments via `/__vitest_attachment__` endpoint
72
- **HTML Middleware**: Serves the main UI HTML with injected configuration
73
- **Static File Middleware**: Serves client assets (CSS, JS, images)
74
- **Coverage Middleware**: Serves HTML coverage reports when available
75

76
## Error Handling
77

78
The plugin includes validation to prevent configuration conflicts:
79

80
```typescript
81
// Example error case
82
if (coveragePath && base === coveragePath) {
83
  throw new Error(
84
    `The ui base path and the coverage path cannot be the same: ${base}, change coverage.reportsDirectory`
85
  );
86
}
87
```
88

89
## Types
90

91
```typescript { .api }
92
interface Plugin {
93
  name: string;
94
  apply: string;
95
  configureServer: {
96
    order: string;
97
    handler: (server: ViteDevServer) => void;
98
  };
99
}
100
```