Plugin Configuration

/**
 * Creates a Vite plugin that generates declaration files from TypeScript and Vue source files
 * @param options - Configuration options for the plugin
 * @returns Configured Vite plugin instance
 */
function dts(options?: PluginOptions): import('vite').Plugin;

import { defineConfig } from "vite";
import dts from "vite-plugin-dts";

// Basic usage with default settings
export default defineConfig({
  plugins: [dts()]
});

// Advanced configuration
export default defineConfig({
  plugins: [
    dts({
      outDir: ["dist", "types"],
      include: ["src/**/*.ts", "src/**/*.vue"],
      exclude: ["src/**/*.test.ts"],
      rollupTypes: true,
      insertTypesEntry: true
    })
  ]
});

interface PluginOptions {
  /** Specify root directory (defaults to Vite config root or process.cwd()) */
  root?: string;
  
  /** Output directory for declaration files (can be array for multiple outputs) */
  outDir?: string | string[];
  
  /** Override root path of entry files (useful in monorepos) */
  entryRoot?: string;
  
  /** Restrict declaration files output to outDir (default: true) */
  strictOutput?: boolean;
  
  /** Override TypeScript compiler options */
  compilerOptions?: ts.CompilerOptions | null;
  
  /** Specify tsconfig.json path for resolving include/exclude globs */
  tsconfigPath?: string;
  
  /** Custom resolvers for non-standard file types (default: []) */
  resolvers?: Resolver[];
  
  /** Parse tsconfig.json paths to aliases for declaration files (default: true) */
  pathsToAliases?: boolean;
  
  /** Exclude paths when transforming aliases (default: []) */
  aliasesExclude?: (string | RegExp)[];
  
  /** Transform '.vue.d.ts' filenames to '.d.ts' (default: false) */
  cleanVueFileName?: boolean;
  
  /** Transform dynamic imports to static imports (default: false, forced true when rollupTypes is true) */
  staticImport?: boolean;
  
  /** Override include glob patterns (relative to root) */
  include?: string | string[];
  
  /** Override exclude glob patterns (default: 'node_modules/**') */
  exclude?: string | string[];
  
  /** Remove pure import statements like 'import "xxx"' (default: true) */
  clearPureImport?: boolean;
  
  /** Generate types entry file(s) based on package.json types property (default: false, forced true when rollupTypes is true) */
  insertTypesEntry?: boolean;
  
  /** Bundle declaration files using @microsoft/api-extractor (default: false) */
  rollupTypes?: boolean;
  
  /** Bundled packages configuration for @microsoft/api-extractor (default: []) */
  bundledPackages?: string[];
  
  /** Override @microsoft/api-extractor configuration */
  rollupConfig?: RollupConfig;
  
  /** Override @microsoft/api-extractor invoke options */
  rollupOptions?: IExtractorInvokeOptions;
  
  /** Copy existing .d.ts source files to outDir (default: false) */
  copyDtsFiles?: boolean;
  
  /** Emit only declaration files, removing all other Vite outputs (default: false) */
  declarationOnly?: boolean;
  
  /** Logging level for this plugin (defaults to Vite config logLevel) */
  logLevel?: LogLevel;
  
  /** Hook called after TypeScript diagnostics are emitted */
  afterDiagnostic?: (diagnostics: readonly ts.Diagnostic[]) => MaybePromise<void>;
  
  /** Hook called before writing each declaration file (return false to skip file) */
  beforeWriteFile?: (
    filePath: string,
    content: string
  ) => MaybePromise<void | false | { filePath?: string; content?: string }>;
  
  /** Hook called after declaration files are bundled with rollupTypes */
  afterRollup?: (result: ExtractorResult) => MaybePromise<void>;
  
  /** Hook called after all declaration files are written */
  afterBuild?: (emittedFiles: Map<string, string>) => MaybePromise<void>;
}

// Root directory configuration
root?: string;

// Output directory (single or multiple)
outDir?: string | string[];

// Entry root for monorepo scenarios
entryRoot?: string;

// Restrict output to specified directories
strictOutput?: boolean;

// Multiple output directories
dts({
  outDir: ["dist/types", "lib/types"]
});

// Monorepo configuration
dts({
  root: "./packages/core",
  entryRoot: "./packages/core/src",
  outDir: "./packages/core/dist"
});

// TypeScript compiler options override
compilerOptions?: ts.CompilerOptions | null;

// Path to specific tsconfig.json file
tsconfigPath?: string;

// File inclusion/exclusion patterns
include?: string | string[];
exclude?: string | string[];

// Override compiler options
dts({
  compilerOptions: {
    target: "ES2020",
    module: "ESNext",
    strict: true
  }
});

// Use specific tsconfig
dts({
  tsconfigPath: "./tsconfig.build.json"
});

// Custom file patterns
dts({
  include: ["src/**/*.ts", "types/**/*.d.ts"],
  exclude: ["**/*.test.ts", "**/*.spec.ts"]
});

// Convert tsconfig paths to Vite aliases
pathsToAliases?: boolean;

// Exclude specific aliases from transformation
aliasesExclude?: (string | RegExp)[];

// Convert dynamic to static imports
staticImport?: boolean;

// Remove pure import statements
clearPureImport?: boolean;

// Disable alias transformation for specific patterns
dts({
  pathsToAliases: true,
  aliasesExclude: [/^@types\//, "virtual:*"]
});

// Force static imports for better bundling
dts({
  staticImport: true,
  clearPureImport: false
});

// Generate main entry declaration files
insertTypesEntry?: boolean;

// Bundle all declarations into single files
rollupTypes?: boolean;

// Copy existing .d.ts files
copyDtsFiles?: boolean;

// Remove non-declaration outputs
declarationOnly?: boolean;

// Clean Vue file naming
cleanVueFileName?: boolean;

// Bundle declarations with entry generation
dts({
  insertTypesEntry: true,
  rollupTypes: true,
  declarationOnly: true
});

// Vue project configuration
dts({
  cleanVueFileName: true,
  include: ["src/**/*.ts", "src/**/*.vue"]
});

/**
 * Called after TypeScript diagnostics are emitted
 * Use diagnostics.length to check for type errors
 */
afterDiagnostic?: (diagnostics: readonly ts.Diagnostic[]) => MaybePromise<void>;

/**
 * Called before writing each declaration file
 * Return false to skip the file, or modify path/content
 */
beforeWriteFile?: (
  filePath: string,
  content: string
) => MaybePromise<void | false | { filePath?: string; content?: string }>;

/**
 * Called after declaration bundling with api-extractor
 */
afterRollup?: (result: ExtractorResult) => MaybePromise<void>;

/**
 * Called after all declaration files are written
 * Receives map of file paths to their content
 */
afterBuild?: (emittedFiles: Map<string, string>) => MaybePromise<void>;

dts({
  afterDiagnostic: async (diagnostics) => {
    if (diagnostics.length > 0) {
      console.warn(`Found ${diagnostics.length} type issues`);
    }
  },
  
  beforeWriteFile: async (filePath, content) => {
    // Add custom header to all declaration files
    if (filePath.endsWith('.d.ts')) {
      return {
        content: `// Generated by vite-plugin-dts\n${content}`
      };
    }
  },
  
  afterBuild: async (emittedFiles) => {
    console.log(`Generated ${emittedFiles.size} declaration files`);
  }
});