0
# Vue CLI Overlay
1

2
Vue CLI Overlay is a placeholder package in the Vue CLI ecosystem. **This package contains no implementation** - it serves as a dependency marker for @vue/cli-service. The actual error overlay functionality is provided by webpack-dev-server's built-in client overlay feature, which is configured and managed by @vue/cli-service during development.
3

4
## Package Information
5

6
- **Package Name**: @vue/cli-overlay
7
- **Package Type**: npm
8
- **Language**: JavaScript (placeholder only)
9
- **Installation**: `npm install @vue/cli-overlay` (typically installed as part of Vue CLI)
10

11
## Core Imports
12

13
**Important**: This package has no exports and cannot be imported directly.
14

15
```javascript
16
// ❌ These imports will fail - the package is empty
17
// const overlay = require("@vue/cli-overlay");
18
// import overlay from "@vue/cli-overlay";
19

20
// ✅ Overlay functionality is configured through Vue CLI service
21
// No direct imports are needed or possible
22
```
23

24
**Note**: The package contains no implementation whatsoever. The src/index.js file is completely empty, and there is no dist/client.js file to import.
25

26
## Basic Usage
27

28
The `@vue/cli-overlay` package **cannot be used directly** as it contains no implementation. The error overlay functionality is built into webpack-dev-server and configured by @vue/cli-service.
29

30
**Overlay Configuration** (handled by Vue CLI service, not this package):
31

32
```javascript
33
// vue.config.js - configures webpack-dev-server overlay
34
module.exports = {
35
  devServer: {
36
    overlay: {
37
      warnings: true,  // Show webpack warnings in browser
38
      errors: true     // Show webpack errors in browser
39
    }
40
  }
41
}
42
```
43

44
**Example Error Scenarios** that trigger webpack-dev-server's overlay:
45

46
```javascript
47
// Compilation errors trigger the overlay
48
import { nonExistentExport } from './missing-module';
49

50
// Runtime errors during development
51
function buggyFunction() {
52
  throw new Error('This will appear in the webpack overlay');
53
}
54

55
// Syntax errors in source code
56
const malformed = {
57
  property: value // Missing quotes - webpack compilation error
58
};
59
```
60

61
**Note**: The overlay functionality comes from webpack-dev-server, not from this package.
62

63
## Architecture
64

65
**Important**: This package provides no functionality itself. It exists only as a placeholder in the Vue CLI ecosystem:
66

67
- **Placeholder Package**: Contains no implementation - src/index.js is empty
68
- **Dependency Marker**: Listed as a dependency in @vue/cli-service/package.json
69
- **Webpack Dev Server Integration**: Actual overlay functionality comes from webpack-dev-server's client.overlay option
70
- **Vue CLI Service Configuration**: @vue/cli-service configures webpack-dev-server's overlay, not this package
71
- **Development-Only**: webpack-dev-server overlay is only active during development mode
72

73
## Capabilities
74

75
### Package Purpose
76

77
This package serves as a placeholder and dependency marker within the Vue CLI ecosystem.
78

79
```javascript { .api }
80
// No API exists - this package is completely empty
81
// src/index.js contains no code (0 bytes)
82
// No exports, functions, or classes are available
83
```
84

85
### Overlay Configuration
86

87
The actual overlay functionality is configured through webpack-dev-server options, managed by @vue/cli-service.
88

89
```javascript { .api }
90
// Webpack dev server overlay configuration (handled by @vue/cli-service)
91
interface WebpackOverlayOptions {
92
  warnings?: boolean;  // Show webpack compilation warnings in overlay
93
  errors?: boolean;    // Show webpack compilation errors in overlay
94
}
95

96
// Configured in @vue/cli-service, not this package
97
type OverlayConfig = boolean | WebpackOverlayOptions;
98
```
99

100
## Integration with Vue CLI
101

102
This package exists only as a dependency marker in `@vue/cli-service/package.json`. It provides no functionality itself.
103

104
### Development Server Integration
105

106
The actual overlay configuration happens in `@vue/cli-service/lib/commands/serve.js`:
107

108
```javascript
109
// Real implementation in @vue/cli-service (not this package)
110
{
111
  client: {
112
    overlay: isProduction 
113
      ? false 
114
      : { warnings: false, errors: true }
115
  }
116
}
117
```
118

119
### Editor Integration
120

121
The overlay works with Vue CLI's editor integration, but this integration is handled by @vue/cli-service:
122

123
```javascript
124
// Editor integration in @vue/cli-service (comment mentions this package)
125
// "this works with vue-devtools & @vue/cli-overlay"
126
app.use('/__open-in-editor', launchEditorMiddleware(/* ... */));
127
```
128

129
**Note**: The comment in @vue/cli-service references this package, but the actual functionality comes from webpack-dev-server and launch-editor-middleware.
130

131
## Types
132

133
```javascript { .api }
134
// This package provides no types - it's empty
135
// Overlay types are part of webpack-dev-server configuration
136

137
// Webpack dev server overlay options (configured by @vue/cli-service)
138
interface WebpackClientOverlayOptions {
139
  warnings?: boolean;  // Show webpack warnings
140
  errors?: boolean;    // Show webpack errors
141
}
142

143
// Vue CLI devServer configuration type
144
type VueDevServerOverlay = boolean | WebpackClientOverlayOptions;
145
```
146

147
## Error Handling
148

149
The webpack-dev-server overlay (not this package) automatically handles and displays:
150

151
- **Compilation Errors**: Syntax errors, type errors, and other webpack build-time issues
152
- **Runtime Errors**: JavaScript runtime exceptions during development (when enabled)
153
- **Webpack Warnings**: Build warnings and deprecation notices from webpack
154
- **Hot Module Replacement Errors**: Issues during HMR updates
155

156
When errors occur, webpack-dev-server displays them in a full-screen overlay with:
157
- Error message and stack trace
158
- File location and line numbers  
159
- Clickable links to open files in your editor (via @vue/cli-service's /__open-in-editor middleware)
160

161
**Note**: All error handling is provided by webpack-dev-server's built-in overlay client, not by this package.
162

163
## Notes
164

165
- **This package is completely empty** - src/index.js contains no code
166
- **No API exists** - there are no functions, classes, or exports to use
167
- **Serves as placeholder** - exists only as a dependency marker in @vue/cli-service
168
- **Overlay functionality** comes entirely from webpack-dev-server's client overlay
169
- **Configuration** is handled by @vue/cli-service through webpack-dev-server options
170
- **No direct usage possible** - the package cannot be imported or used directly
171
- **Works with editor integration** through @vue/cli-service's middleware, not this package