Vue TSConfig

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.

Package Information

• Package Name: @vue/tsconfig
• Package Type: npm
• Language: JavaScript (TypeScript configurations)
• Installation: npm add -D @vue/tsconfig

Core Imports

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

{
  "extends": "@vue/tsconfig/tsconfig.json"
}

Multiple configurations can be extended together:

{
  "extends": [
    "@vue/tsconfig/tsconfig.dom.json",
    "@vue/tsconfig/tsconfig.lib.json"
  ]
}

Basic Usage

{
  "extends": "@vue/tsconfig/tsconfig.dom.json",
  "compilerOptions": {
    "outDir": "./dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

For Node.js environments with Vue:

{
  "extends": [
    "@tsconfig/node22/tsconfig.json",
    "@vue/tsconfig/tsconfig.json"
  ],
  "compilerOptions": {
    "types": ["node"]
  }
}

Requirements

• TypeScript: >= 5.0
• Vue.js: >= 3.4 (optional peer dependency)

Capabilities

Base Configuration

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

{
  "extends": "@vue/tsconfig/tsconfig.json"
}

Configuration Details:

• Module System: ESNext modules with bundler resolution
• JSX Settings: "jsx": "preserve", "jsxImportSource": "vue"
• Strict Checking: Full strict mode enabled
• Bundler Features: JSON imports, TypeScript extension imports supported
• No Emit: "noEmit": true (no file output by default)
• Target: ESNext with modern features
• Safety Features: "noUncheckedIndexedAccess": true for safer array/object access

Compiler Options:

{
  "compilerOptions": {
    "noEmit": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "allowImportingTsExtensions": true,
    "moduleDetection": "force",
    "jsx": "preserve",
    "jsxImportSource": "vue",
    "noImplicitThis": true,
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "verbatimModuleSyntax": true,
    "target": "ESNext",
    "useDefineForClassFields": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "libReplacement": false,
    "skipLibCheck": true
  }
}

DOM Configuration

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

{
  "extends": "@vue/tsconfig/tsconfig.dom.json"
}

Configuration Details:

• Extends: Base configuration (./tsconfig.json)
• DOM Types: Includes ES2020, DOM, and DOM.Iterable libraries
• Type Isolation: Empty types array prevents Node.js type pollution
• ES Target: ES2020 to align with Vite defaults

Compiler Options:

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "types": []
  }
}

Library Configuration

Configuration for library development, enabling declaration file emission.

{
  "extends": [
    "@vue/tsconfig/tsconfig.dom.json",
    "@vue/tsconfig/tsconfig.lib.json"
  ]
}

Configuration Details:

• Declaration Output: Enables TypeScript declaration file generation
• Emit Mode: Declaration files only, no JavaScript output
• Strict Checking: Enhanced type checking for library compatibility
• Library Focus: Designed for component libraries and npm packages

Compiler Options:

{
  "compilerOptions": {
    "noEmit": false,
    "declaration": true,
    "emitDeclarationOnly": true,
    "skipLibCheck": false
  }
}

Configuration Combinations

Browser Application

For standard Vue web applications:

{
  "extends": "@vue/tsconfig/tsconfig.dom.json"
}

Component Library

For building Vue component libraries with type declarations:

{
  "extends": [
    "@vue/tsconfig/tsconfig.dom.json",
    "@vue/tsconfig/tsconfig.lib.json"
  ]
}

Server-Side Rendering

For Vue applications with SSR or Node.js integration:

{
  "extends": [
    "@tsconfig/node22/tsconfig.json",
    "@vue/tsconfig/tsconfig.json"
  ],
  "compilerOptions": {
    "types": ["node"]
  }
}

Testing Environments

For testing with tools like Vitest:

{
  "extends": [
    "@vue/tsconfig/tsconfig.dom.json"
  ],
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

Migration from v0.2.x

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

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

Compatibility Issues

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

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

{
  "extends": "@vue/tsconfig/tsconfig.dom.json",
  "compilerOptions": {
    "resolvePackageJsonExports": false
  }
}

Error Handling

Common issues and solutions:

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

Types

TSConfig Schema

The configurations follow the standard TypeScript configuration schema:

interface TSConfig {
  extends?: string | string[];
  compilerOptions?: {
    // Core options
    target?: string;
    module?: string;
    moduleResolution?: "node" | "bundler";
    
    // Vue-specific
    jsx?: "preserve" | "react" | "react-jsx";
    jsxImportSource?: string;
    
    // Output
    noEmit?: boolean;
    declaration?: boolean;
    emitDeclarationOnly?: boolean;
    
    // Type checking
    strict?: boolean;
    noImplicitThis?: boolean;
    noUncheckedIndexedAccess?: boolean;
    
    // Libraries and types
    lib?: string[];
    types?: string[];
    
    // Module resolution
    resolveJsonModule?: boolean;
    allowImportingTsExtensions?: boolean;
    resolvePackageJsonExports?: boolean;
    
    // Other
    skipLibCheck?: boolean;
    esModuleInterop?: boolean;
    forceConsistentCasingInFileNames?: boolean;
    libReplacement?: boolean;
    verbatimModuleSyntax?: boolean;
    useDefineForClassFields?: boolean;
    moduleDetection?: "auto" | "legacy" | "force";
  };
  include?: string[];
  exclude?: string[];
}