TypeScript Processing

TypeScript compilation and declaration file generation with support for custom tsconfig files and path alias resolution.

Capabilities

Emit TypeScript Declarations

Generates TypeScript declaration files (.d.ts) for the package.

/**
 * Generate TypeScript declaration files
 * @param input - Input directory path
 * @param output - Output directory path for temp files
 * @param final_output - Final output directory path
 * @param cwd - Current working directory
 * @param alias - Path alias mapping
 * @param files - Array of files to process
 * @param tsconfig - Optional path to tsconfig file
 */
function emit_dts(
  input: string,
  output: string,
  final_output: string,
  cwd: string,
  alias: Record<string, string>,
  files: File[],
  tsconfig?: string
): Promise<void>;

Usage Examples:

import { emit_dts } from "@sveltejs/package/src/typescript.js";

// Generate declaration files
await emit_dts(
  "src/lib",           // input directory
  ".svelte-kit/temp",  // temp output
  "dist",              // final output
  process.cwd(),       // working directory
  { '$lib': 'src/lib' }, // aliases
  files,               // file list
  "tsconfig.json"      // tsconfig path
);

// Generate without custom tsconfig
await emit_dts(
  "src/lib",
  ".svelte-kit/temp", 
  "dist",
  process.cwd(),
  { '$lib': 'src/lib' },
  files
);

Transpile TypeScript

Transpiles TypeScript source code to JavaScript.

/**
 * Transpile TypeScript to JavaScript
 * @param tsconfig - Path to tsconfig file (optional)
 * @param filename - Source file path
 * @param source - TypeScript source code
 * @returns Promise resolving to transpiled JavaScript
 */
function transpile_ts(
  tsconfig: string | undefined,
  filename: string,
  source: string
): Promise<string>;

Usage Examples:

import { transpile_ts } from "@sveltejs/package/src/typescript.js";

// Transpile with custom tsconfig
const jsCode = await transpile_ts(
  "tsconfig.json",
  "src/lib/utils.ts",
  `
  export function add(a: number, b: number): number {
    return a + b;
  }
  `
);

// Transpile with default settings
const jsCode = await transpile_ts(
  undefined,
  "src/lib/helpers.ts",
  `
  interface User {
    name: string;
    age: number;
  }
  
  export const createUser = (name: string, age: number): User => ({ name, age });
  `
);

TypeScript Processing Pipeline

Declaration File Generation

The emit_dts function:

1. Configuration: Loads TypeScript configuration from tsconfig
2. Program Creation: Creates TypeScript compiler program
3. Analysis: Analyzes source files and their dependencies
4. Generation: Generates .d.ts files with proper type information
5. Alias Resolution: Resolves path aliases in generated declarations
6. Output: Writes declaration files to final output directory

Transpilation Process

The transpile_ts function:

1. Configuration Loading: Loads compiler options from tsconfig
2. Source Processing: Parses TypeScript source code
3. Type Checking: Performs type checking (optional, based on config)
4. Code Generation: Generates JavaScript code
5. Source Maps: Generates source maps if configured

Path Alias Resolution

Both functions support path alias resolution:

• $lib aliases are resolved to the configured library directory
• Custom aliases from kit.alias configuration are supported
• Relative path resolution maintains proper import relationships

Configuration Integration

TSConfig Support

The TypeScript processing integrates with tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "strict": true,
    "paths": {
      "$lib": ["src/lib"],
      "$lib/*": ["src/lib/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["**/*.test.ts"]
}

Compiler Options

Key compiler options supported:

• Target: ES version for output JavaScript
• Module: Module system (ESNext, CommonJS, etc.)
• Declaration: Generate .d.ts files
• Source Maps: Generate source map files
• Strict Mode: TypeScript strict type checking
• Path Mapping: Path alias resolution

Error Handling

Compilation Errors

TypeScript compilation errors are handled gracefully:

• Syntax errors stop the build process
• Type errors can be configured to warn or fail
• Missing dependency errors provide helpful messages

Configuration Errors

• Invalid tsconfig files produce clear error messages
• Missing tsconfig falls back to default configuration
• Path alias errors show resolution attempts

Integration with Build Process

The TypeScript processing integrates with the main build system:

1. File Analysis: Files are analyzed to determine TypeScript processing needs
2. Declaration Generation: .d.ts files are generated if types option is enabled
3. Transpilation: .ts files are transpiled to .js during file processing
4. Alias Resolution: Path aliases are resolved in both source and declaration files

Types

interface File {
  name: string;
  dest: string;
  base: string;
  is_svelte: boolean;
}