Guide
API
Examples
Guide
API
Examples

Declaration Generator

The Declaration Generator module is responsible for creating and managing the TypeScript declaration files required for auto-import functionality. It provides functions to generate placeholder declaration files that will be automatically updated by the auto-import plugins during development.

API Reference

generateDeclarationFiles

Signature:

1function generateDeclarationFiles(
2  options: GenerateDeclarationFilesOptions
3): Promise<GenerateDeclarationFilesResult>;

Parameters:

  • options: GenerateDeclarationFilesOptions - Configuration options for declaration file generation
    • path?: string - The path to the project directory (defaults to current directory)

Returns:

  • Promise<GenerateDeclarationFilesResult> - A promise that resolves to the generation result
    • success: boolean - Whether the generation was successful
    • componentsDeclarationPath: string - The path to the components declaration file
    • autoImportsDeclarationPath: string - The path to the auto-imports declaration file
    • filesCreated: boolean - Whether new files were created or existing files were preserved

Example:

1import { generateDeclarationFiles } from "ew-auto-import-tool";
2
3async function setupDeclarations() {
4  try {
5    const result = await generateDeclarationFiles({
6      path: "./my-vue-project",
7    });
8
9    if (result.success) {
10      console.log("Declaration files generated successfully:");
11      console.log(`Components: ${result.componentsDeclarationPath}`);
12      console.log(`Auto-imports: ${result.autoImportsDeclarationPath}`);
13
14      if (result.filesCreated) {
15        console.log("New declaration files were created");
16      } else {
17        console.log("Existing declaration files were preserved");
18      }
19    } else {
20      console.error("Failed to generate declaration files");
21    }
22  } catch (error) {
23    console.error("Error generating declaration files:", error);
24  }
25}
26
27setupDeclarations();

Implementation Details

The Declaration Generator performs the following operations:

  1. File Path Resolution

    • Determines the paths for the declaration files
    • By default, creates files in the project root directory

  2. File Existence Check

    • Checks if declaration files already exist
    • Preserves existing files to avoid overwriting user modifications

  3. Template Generation

    • Creates placeholder declaration files with minimal content
    • These files will be automatically updated by the plugins during development

Declaration File Templates

The module generates two declaration files:

components.d.ts

1/* eslint-disable */
2/* prettier-ignore */
3// @ts-nocheck
4// Generated by unplugin-vue-components
5// Read more: https://github.com/vuejs/core/pull/3399
6import '@vue/runtime-core'
7
8export {};
9
10declare module "@vue/runtime-core" {
11  export interface GlobalComponents {
12    // This will be filled automatically by the plugin
13  }
14}

auto-imports.d.ts

1/* eslint-disable */
2/* prettier-ignore */
3// @ts-nocheck
4// Generated by unplugin-auto-import
5export {}
6declare global {
7  // This will be filled automatically by the plugin
8}

Source Code Analysis

The Declaration Generator uses the file system to create declaration files. It follows these steps:

  1. Determine the paths for the declaration files
  2. Check if the files already exist
  3. If they don't exist, create them with placeholder content
  4. Return the paths and creation status
1// Simplified implementation
2async function generateDeclarationFiles(
3  options: GenerateDeclarationFilesOptions
4): Promise<GenerateDeclarationFilesResult> {
5  const projectPath = options.path || process.cwd();
6
7  // Determine file paths
8  const componentsDeclarationPath = path.join(projectPath, "components.d.ts");
9  const autoImportsDeclarationPath = path.join(
10    projectPath,
11    "auto-imports.d.ts"
12  );
13
14  // Check if files already exist
15  const componentsExists = fs.existsSync(componentsDeclarationPath);
16  const autoImportsExists = fs.existsSync(autoImportsDeclarationPath);
17
18  let filesCreated = false;
19
20  // Create components declaration file if it doesn't exist
21  if (!componentsExists) {
22    const componentsTemplate = `/* eslint-disable */
23/* prettier-ignore */
24// @ts-nocheck
25// Generated by unplugin-vue-components
26// Read more: https://github.com/vuejs/core/pull/3399
27import '@vue/runtime-core'
28
29export {}
30
31declare module '@vue/runtime-core' {
32  export interface GlobalComponents {
33    // This will be filled automatically by the plugin
34  }
35}`;
36
37    fs.writeFileSync(componentsDeclarationPath, componentsTemplate, "utf-8");
38    filesCreated = true;
39  }
40
41  // Create auto-imports declaration file if it doesn't exist
42  if (!autoImportsExists) {
43    const autoImportsTemplate = `/* eslint-disable */
44/* prettier-ignore */
45// @ts-nocheck
46// Generated by unplugin-auto-import
47export {}
48declare global {
49  // This will be filled automatically by the plugin
50}`;
51
52    fs.writeFileSync(autoImportsDeclarationPath, autoImportsTemplate, "utf-8");
53    filesCreated = true;
54  }
55
56  return {
57    success: true,
58    componentsDeclarationPath,
59    autoImportsDeclarationPath,
60    filesCreated,
61  };
62}

Error Handling

The Declaration Generator includes robust error handling to provide clear feedback when issues are encountered:

  • File system access errors
  • Permission issues when creating files
  • Path resolution errors

These errors are propagated to the caller with descriptive messages to help users troubleshoot issues.

Related Modules

ON THIS PAGE