0
# Vue TSConfig
1

2
Vue TSConfig provides TypeScript configuration presets specifically designed for Vue.js projects. It offers three main configurations: a base runtime-agnostic configuration for general Vue development, a DOM-focused configuration for browser environments, and a library configuration for projects that need to emit declaration files.
3

4
## Package Information
5

6
- **Package Name**: @vue/tsconfig
7
- **Package Type**: npm
8
- **Language**: JavaScript (TypeScript configurations)
9
- **Installation**: `npm add -D @vue/tsconfig`
10

11
## Core Imports
12

13
Vue TSConfig configurations are imported by extending them in your `tsconfig.json`:
14

15
```json
16
{
17
  "extends": "@vue/tsconfig/tsconfig.json"
18
}
19
```
20

21
Multiple configurations can be extended together:
22

23
```json
24
{
25
  "extends": [
26
    "@vue/tsconfig/tsconfig.dom.json",
27
    "@vue/tsconfig/tsconfig.lib.json"
28
  ]
29
}
30
```
31

32
## Basic Usage
33

34
```json
35
{
36
  "extends": "@vue/tsconfig/tsconfig.dom.json",
37
  "compilerOptions": {
38
    "outDir": "./dist"
39
  },
40
  "include": ["src/**/*"],
41
  "exclude": ["node_modules"]
42
}
43
```
44

45
For Node.js environments with Vue:
46

47
```json
48
{
49
  "extends": [
50
    "@tsconfig/node22/tsconfig.json",
51
    "@vue/tsconfig/tsconfig.json"
52
  ],
53
  "compilerOptions": {
54
    "types": ["node"]
55
  }
56
}
57
```
58

59
## Requirements
60

61
- **TypeScript**: >= 5.0
62
- **Vue.js**: >= 3.4 (optional peer dependency)
63

64
## Capabilities
65

66
### Base Configuration
67

68
Runtime-agnostic TypeScript configuration providing core Vue.js settings.
69

70
```json { .api }
71
{
72
  "extends": "@vue/tsconfig/tsconfig.json"
73
}
74
```
75

76
**Configuration Details:**
77
- **Module System**: ESNext modules with bundler resolution
78
- **JSX Settings**: `"jsx": "preserve"`, `"jsxImportSource": "vue"`
79
- **Strict Checking**: Full strict mode enabled
80
- **Bundler Features**: JSON imports, TypeScript extension imports supported
81
- **No Emit**: `"noEmit": true` (no file output by default)
82
- **Target**: ESNext with modern features
83
- **Safety Features**: `"noUncheckedIndexedAccess": true` for safer array/object access
84

85
**Compiler Options:**
86

87
```json { .api }
88
{
89
  "compilerOptions": {
90
    "noEmit": true,
91
    "module": "ESNext",
92
    "moduleResolution": "bundler",
93
    "resolveJsonModule": true,
94
    "allowImportingTsExtensions": true,
95
    "moduleDetection": "force",
96
    "jsx": "preserve",
97
    "jsxImportSource": "vue",
98
    "noImplicitThis": true,
99
    "strict": true,
100
    "noUncheckedIndexedAccess": true,
101
    "verbatimModuleSyntax": true,
102
    "target": "ESNext",
103
    "useDefineForClassFields": true,
104
    "esModuleInterop": true,
105
    "forceConsistentCasingInFileNames": true,
106
    "libReplacement": false,
107
    "skipLibCheck": true
108
  }
109
}
110
```
111

112
### DOM Configuration
113

114
Configuration optimized for browser/DOM environments, extending the base configuration.
115

116
```json { .api }
117
{
118
  "extends": "@vue/tsconfig/tsconfig.dom.json"
119
}
120
```
121

122
**Configuration Details:**
123
- **Extends**: Base configuration (`./tsconfig.json`)
124
- **DOM Types**: Includes ES2020, DOM, and DOM.Iterable libraries
125
- **Type Isolation**: Empty types array prevents Node.js type pollution
126
- **ES Target**: ES2020 to align with Vite defaults
127

128
**Compiler Options:**
129

130
```json { .api }
131
{
132
  "extends": "./tsconfig.json",
133
  "compilerOptions": {
134
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
135
    "types": []
136
  }
137
}
138
```
139

140
### Library Configuration
141

142
Configuration for library development, enabling declaration file emission.
143

144
```json { .api }
145
{
146
  "extends": [
147
    "@vue/tsconfig/tsconfig.dom.json",
148
    "@vue/tsconfig/tsconfig.lib.json"
149
  ]
150
}
151
```
152

153
**Configuration Details:**
154
- **Declaration Output**: Enables TypeScript declaration file generation
155
- **Emit Mode**: Declaration files only, no JavaScript output
156
- **Strict Checking**: Enhanced type checking for library compatibility
157
- **Library Focus**: Designed for component libraries and npm packages
158

159
**Compiler Options:**
160

161
```json { .api }
162
{
163
  "compilerOptions": {
164
    "noEmit": false,
165
    "declaration": true,
166
    "emitDeclarationOnly": true,
167
    "skipLibCheck": false
168
  }
169
}
170
```
171

172
## Configuration Combinations
173

174
### Browser Application
175

176
For standard Vue web applications:
177

178
```json { .api }
179
{
180
  "extends": "@vue/tsconfig/tsconfig.dom.json"
181
}
182
```
183

184
### Component Library
185

186
For building Vue component libraries with type declarations:
187

188
```json { .api }
189
{
190
  "extends": [
191
    "@vue/tsconfig/tsconfig.dom.json",
192
    "@vue/tsconfig/tsconfig.lib.json"
193
  ]
194
}
195
```
196

197
### Server-Side Rendering
198

199
For Vue applications with SSR or Node.js integration:
200

201
```json { .api }
202
{
203
  "extends": [
204
    "@tsconfig/node22/tsconfig.json",
205
    "@vue/tsconfig/tsconfig.json"
206
  ],
207
  "compilerOptions": {
208
    "types": ["node"]
209
  }
210
}
211
```
212

213
### Testing Environments
214

215
For testing with tools like Vitest:
216

217
```json { .api }
218
{
219
  "extends": [
220
    "@vue/tsconfig/tsconfig.dom.json"
221
  ],
222
  "compilerOptions": {
223
    "types": ["vitest/globals"]
224
  }
225
}
226
```
227

228
## Migration from v0.2.x
229

230
Key breaking changes in v0.3.x and later:
231

232
- **File Rename**: `tsconfig.web.json` → `tsconfig.dom.json`
233
- **Node.js Config**: `tsconfig.node.json` removed (use `@tsconfig/nodeX` instead)
234
- **Module Resolution**: Changed from `"node"` to `"bundler"`
235
- **Library Target**: DOM config now targets ES2020 (was ES2016)
236

237
### Compatibility Issues
238

239
Some packages may have issues with the new `"bundler"` resolution mode:
240

241
- **Package Exports**: Honors `exports` field in package.json
242
- **Affected Packages**: vue-i18n@9.2.2, vuetify@3.2.3, v-calendar@3.0.3
243
- **Workaround**: Override `"resolvePackageJsonExports": false` if needed
244

245
```json { .api }
246
{
247
  "extends": "@vue/tsconfig/tsconfig.dom.json",
248
  "compilerOptions": {
249
    "resolvePackageJsonExports": false
250
  }
251
}
252
```
253

254
## Error Handling
255

256
Common issues and solutions:
257

258
- **Module Resolution Errors**: Ensure packages support the `exports` field or disable `resolvePackageJsonExports`
259
- **JSX Issues**: Verify `jsx: "preserve"` and `jsxImportSource: "vue"` are not overridden
260
- **Type Errors**: Check that `strict: true` requirements are met
261
- **Import Errors**: Use `.vue` extensions with `allowImportingTsExtensions: true`
262

263
## Types
264

265
### TSConfig Schema
266

267
The configurations follow the standard TypeScript configuration schema:
268

269
```typescript { .api }
270
interface TSConfig {
271
  extends?: string | string[];
272
  compilerOptions?: {
273
    // Core options
274
    target?: string;
275
    module?: string;
276
    moduleResolution?: "node" | "bundler";
277
    
278
    // Vue-specific
279
    jsx?: "preserve" | "react" | "react-jsx";
280
    jsxImportSource?: string;
281
    
282
    // Output
283
    noEmit?: boolean;
284
    declaration?: boolean;
285
    emitDeclarationOnly?: boolean;
286
    
287
    // Type checking
288
    strict?: boolean;
289
    noImplicitThis?: boolean;
290
    noUncheckedIndexedAccess?: boolean;
291
    
292
    // Libraries and types
293
    lib?: string[];
294
    types?: string[];
295
    
296
    // Module resolution
297
    resolveJsonModule?: boolean;
298
    allowImportingTsExtensions?: boolean;
299
    resolvePackageJsonExports?: boolean;
300
    
301
    // Other
302
    skipLibCheck?: boolean;
303
    esModuleInterop?: boolean;
304
    forceConsistentCasingInFileNames?: boolean;
305
    libReplacement?: boolean;
306
    verbatimModuleSyntax?: boolean;
307
    useDefineForClassFields?: boolean;
308
    moduleDetection?: "auto" | "legacy" | "force";
309
  };
310
  include?: string[];
311
  exclude?: string[];
312
}
313
```