TypeScript Integration

/**
 * TypeScript declaration configuration
 */
interface DeclarationOptions {
  /** Generate TypeScript declaration for global components */
  dts?: boolean | string;
  /** Only provide types of components in library (registered globally) */
  types?: TypeImport[];
}

interface TypeImport {
  /** Import source module */
  from: string;
  /** Type names to import */
  names: string[];
}

// Basic declaration generation
Components({
  dts: true, // Generates components.d.ts in project root
});

// Custom declaration file path
Components({
  dts: "src/types/auto-components.d.ts",
});

// Type-only imports for global components
Components({
  types: [
    {
      from: "vue-router",
      names: ["RouterLink", "RouterView"],
    },
    {
      from: "@/types/global-components",
      names: ["GlobalHeader", "GlobalFooter"],
    },
  ],
});

/**
 * Public plugin API interface
 */
interface PublicPluginAPI {
  /** Resolves a component using the configured resolvers */
  findComponent(name: string, filename?: string): Promise<ComponentInfo | undefined>;
  /** Obtain an import statement for a resolved component */
  stringifyImport(info: ComponentInfo): string;
}

/**
 * Component information interface
 */
interface ComponentInfo {
  /** Import alias name */
  as?: string;
  /** Component name */
  name?: string;
  /** Import path or module name */
  from: string;
  /** Side effect imports (CSS, etc.) */
  sideEffects?: SideEffectsInfo;
}

// Access plugin API in Vite
import Components from "unplugin-vue-components/vite";

const plugin = Components({
  dirs: ["src/components"],
});

// Plugin API is available on the returned plugin
export default defineConfig({
  plugins: [
    vue(),
    plugin,
  ],
});

// Use API programmatically
const api = plugin.api;
const component = await api.findComponent("MyButton");
if (component) {
  const importStatement = api.stringifyImport(component);
  console.log(importStatement); // import MyButton from '@/components/MyButton.vue'
}

/**
 * Type-safe configuration interface
 */
interface TypeSafeOptions {
  /** Vue version for proper type generation */
  version?: 2 | 2.7 | 3;
  /** Transformer selection affects type generation */
  transformer?: "vue2" | "vue3";
  /** Allow component overrides without warnings */
  allowOverrides?: boolean;
}

// Explicit Vue version for accurate types
Components({
  version: 3, // Ensures Vue 3 component types
  transformer: "vue3",
  dts: true,
});

// Type-safe overrides
Components({
  allowOverrides: false, // Warn about component name conflicts
  dts: true,
});

/**
 * Example generated declaration file structure
 */
declare module "@vue/runtime-core" {
  export interface GlobalComponents {
    // Local components
    HelloWorld: typeof import("./src/components/HelloWorld.vue")["default"];
    MyButton: typeof import("./src/components/MyButton.vue")["default"];
    
    // UI library components (via resolvers)
    ElButton: typeof import("element-plus")["ElButton"];
    ElCard: typeof import("element-plus")["ElCard"];
    
    // Namespaced components
    FormInput: typeof import("./src/components/form/Input.vue")["default"];
    FormSelect: typeof import("./src/components/form/Select.vue")["default"];
  }
}

export {};

// VS Code integration
Components({
  dts: true,
  // Ensure declarations are updated during development
  dirs: ["src/components"],
  deep: true,
  // Enable for better IntelliSense
  directoryAsNamespace: true,
});

// WebStorm/IntelliJ integration
Components({
  dts: "types/components.d.ts", // Place in types directory
  extensions: ["vue", "tsx"], // Support all relevant file types
});

/**
 * Vue 3 specific type configuration
 */
interface Vue3TypeOptions {
  /** Transform user resolve functions for better TypeScript support */
  transformerUserResolveFunctions?: boolean;
  /** Support for script setup syntax */
  scriptSetup?: boolean;
}

// Vue 3 + TypeScript + script setup
Components({
  version: 3,
  transformer: "vue3",
  transformerUserResolveFunctions: true,
  dts: true,
});

// In your Vue components
// <script setup lang="ts">
// // No imports needed - components are auto-imported with full typing
// </script>
//
// <template>
//   <HelloWorld /> <!-- Fully typed! -->
//   <ElButton type="primary" /> <!-- UI library types work too! -->
// </template>

/**
 * Custom type definition configuration
 */
interface CustomTypeOptions {
  /** Additional type imports */
  types?: TypeImport[];
  /** Path transformation for custom types */
  importPathTransform?: (path: string) => string | undefined;
}

// Custom global component types
Components({
  dts: true,
  types: [
    // Global layout components
    {
      from: "@/layouts",
      names: ["DefaultLayout", "AdminLayout"],
    },
    // Third-party components not handled by resolvers
    {
      from: "my-custom-ui-lib",
      names: ["CustomButton", "CustomModal"],
    },
  ],
});

// With path transformation
Components({
  dts: true,
  importPathTransform: (path) => {
    // Transform @ alias in type definitions
    return path.replace(/^@\//, "./src/");
  },
});

const isDev = process.env.NODE_ENV === "development";

Components({
  // More detailed types in development
  dts: isDev ? "src/types/components.development.d.ts" : true,
  
  // More permissive in development
  allowOverrides: isDev,
  
  // Additional checks in development
  version: 3,
  transformer: "vue3",
});

// package.json scripts
{
  "scripts": {
    "type-check": "vue-tsc --noEmit",
    "build": "vue-tsc && vite build"
  }
}

// tsconfig.json
{
  "compilerOptions": {
    "types": ["node", "vite/client"]
  },
  "include": [
    "src/**/*",
    "components.d.ts" // Include generated declarations
  ]
}

// vite.config.ts with type checking
Components({
  dts: true,
  // Ensure types are generated before TypeScript compilation
  dirs: ["src/components"],
});

// .gitignore - whether to commit generated declarations
# Option 1: Commit for team consistency (recommended)
# components.d.ts

# Option 2: Don't commit, generate locally
components.d.ts

// Auto-regeneration during development
Components({
  dts: true,
  // Will update declarations when components change
  dirs: ["src/components"],
  extensions: ["vue", "tsx"],
});

// Issue: Components not recognized by TypeScript
// Solution: Ensure declaration file is generated and included

Components({
  dts: true, // Make sure this is enabled
});

// Check tsconfig.json includes the declaration file
{
  "include": ["src/**/*", "components.d.ts"]
}

// Issue: Wrong component types
// Solution: Specify correct Vue version and transformer

Components({
  version: 3, // Match your actual Vue version
  transformer: "vue3",
  dts: true,
});

// Issue: Resolver components not typed
// Solution: Use resolvers that support TypeScript

Components({
  resolvers: [
    ElementPlusResolver(), // Has built-in TypeScript support
  ],
  dts: true,
});