Vue TSC

Vue TSC is a command-line TypeScript compiler specifically designed for Vue 3 applications. It extends the standard TypeScript compiler to understand Vue Single File Components (.vue files), enabling type checking and declaration file generation for Vue projects with full type safety.

Package Information

• Package Name: vue-tsc
• Package Type: npm
• Language: TypeScript
• Installation: npm install vue-tsc typescript

Core Imports

import { run } from "vue-tsc";

For CommonJS:

const { run } = require("vue-tsc");

Basic Usage

CLI Usage (most common):

# Type checking only (recommended for CI/CD)
vue-tsc --noEmit

# Generate declaration files for Vue components
vue-tsc --declaration --emitDeclarationOnly

# Use with TypeScript build mode
vue-tsc --build

# Pass any TypeScript compiler options
vue-tsc --strict --target ES2020

Programmatic Usage:

import { run } from "vue-tsc";

// Use default TypeScript compiler
run();

// Use custom TypeScript compiler path
run("/path/to/custom/typescript/lib/tsc");

Architecture

Vue TSC integrates several key components to provide Vue-aware TypeScript compilation:

• TypeScript Compiler Integration: Wraps the standard TypeScript compiler (tsc) with Vue language support
• Vue Language Plugin: Uses @vue/language-core to parse and understand Vue Single File Components
• Volar Integration: Leverages @volar/typescript for high-performance TypeScript language services
• Extension Management: Dynamically handles file extensions based on Vue project configuration
• CLI Wrapper: Provides a command-line interface that passes through TypeScript compiler options

Capabilities

Programmatic API

Core function for integrating Vue TypeScript compilation into custom build tools or processes.

/**
 * Executes TypeScript compilation with Vue Single File Component support
 * @param tscPath - Optional path to TypeScript compiler executable
 * @returns Result from the underlying TypeScript compilation process
 */
function run(tscPath?: string): any;

The run function:

• Default Behavior: Uses require.resolve('typescript/lib/tsc') when no path provided
• Vue Integration: Automatically configures Vue language plugin for .vue file support
• Extension Handling: Dynamically adapts to project-specific file extensions
• Error Recovery: Implements retry logic for configuration changes during compilation
• TypeScript Passthrough: Forwards compilation to underlying TypeScript compiler with Vue enhancements

CLI Interface

Command-line tool that provides Vue-aware TypeScript compilation for development workflows.

# Primary CLI command
vue-tsc [typescript-options]

# Common usage patterns:
vue-tsc --noEmit                    # Type checking only
vue-tsc --declaration --emitDeclarationOnly  # Generate .d.ts files

CLI Features:

• TypeScript Option Support: Accepts all standard TypeScript compiler flags and options
• Project Configuration: Reads from tsconfig.json with Vue-specific extensions
• Build Mode: Supports --build flag for TypeScript project references
• Output Control: Compatible with --noEmit, --declaration, and other output options
• Integration Ready: Designed for use in npm scripts, CI/CD pipelines, and build processes

Types

// Return type from run() function - matches TypeScript compiler output
type CompilationResult = any;

// Internal Vue configuration options (from @vue/language-core)
interface VueCompilerOptions {
  extensions: string[];
  // Additional Vue-specific compiler options
}

// Vue language plugin configuration
interface VueLanguagePlugin {
  // Plugin interface for TypeScript language service integration
}

Dependencies

Vue TSC requires these peer and runtime dependencies:

• TypeScript: >=5.0.0 (peer dependency)
• @volar/typescript: 2.4.23 (TypeScript language service integration)
• @vue/language-core: 3.0.6 (Vue language support and SFC parsing)

Error Handling

The tool handles several error scenarios:

• Extension Changes: Automatically retries compilation if Vue file extensions change during processing
• Configuration Errors: Passes through TypeScript configuration errors with Vue context
• Missing Dependencies: Requires TypeScript as a peer dependency with clear error messages
• File Processing: Handles .vue file parsing errors through the Vue language core

Common Use Cases

Development Workflow:

# Add to package.json scripts
{
  "scripts": {
    "type-check": "vue-tsc --noEmit",
    "build-types": "vue-tsc --declaration --emitDeclarationOnly"
  }
}

CI/CD Pipeline:

# Type checking in continuous integration
npm run type-check

Library Development:

# Generate declaration files for Vue component libraries
vue-tsc --declaration --emitDeclarationOnly --outDir dist/types