How Celeris Web's Auto-Import System Works: Unplugin Architecture Deep Dive

Celeris Web uses two unplugin-based Vite plugins—unplugin-auto-import for APIs and composables and unplugin-vue-components for UI components—to automatically inject import statements at build-time, eliminating manual imports across the monorepo.

The kirklin/celeris-web repository implements a zero-config developer experience by leveraging the unplugin ecosystem to transform source code during compilation. This auto-import system intercepts source files in the Vite pipeline, detects usage of predefined APIs and components, and rewrites the AST to include the necessary import declarations while generating TypeScript definition files for IDE support.

The Dual-Plugin Architecture

Celeris Web's auto-import mechanism relies on two distinct plugins working in tandem during the build process. The system eliminates manual import overhead while maintaining full TypeScript support through automatically generated declaration files.

Automatic API and Composable Imports

The system uses unplugin-auto-import to handle Vue APIs and custom composables without explicit import statements. In packages/shared/vite/src/plugins/unpluginAutoImport.ts, the plugin receives a whitelist of packages including vue, vue-router, @celeris/ca-components, and @celeris/hooks, alongside directories such as src/composables and src/store.

When the compiler encounters an identifier matching one of the listed exports—such as ref from Vue or useScreen from @celeris/hooks—the plugin automatically prepends the corresponding import statement to the file. The configuration also generates autoResolver/auto-imports.d.ts to provide TypeScript with type definitions for these auto-imported symbols.

Automatic Component Resolution

For UI components, Celeris Web implements unplugin-vue-components with a custom resolver defined in packages/shared/vite/src/plugins/unpluginVueComponets.ts. The CelerisAdminResolver maps component names following specific naming conventions to their source packages:

• N* or n-* prefixes resolve to @celeris/ca-components (Naive UI components)
• CA* or ca-* prefixes resolve to @celeris/components (custom Celeris components)

When scanning .vue files, the plugin examines template tags and runs the resolver against each component name. If a match is found, the resolver returns { name, from }, triggering the plugin to inject the appropriate import declaration. This process generates autoResolver/components.d.ts for TypeScript recognition.

Build-Time Code Transformation

The auto-import system operates during both development and production builds through AST manipulation. This build-time transformation ensures zero runtime overhead while maintaining clean source code.

Identifier Detection and Injection

As Vite processes source files, unplugin-auto-import parses the AST to detect bare identifiers that match the configured whitelist. For example, when encountering const count = ref(0), the plugin rewrites the module to include:

import { ref } from 'vue'

This transformation occurs before the code reaches the browser, ensuring runtime compatibility while maintaining clean source code. The injection happens transparently during the compilation phase.

Template Scanning and Import Insertion

Simultaneously, unplugin-vue-components walks the template AST of Vue single-file components. When it identifies tags like <NButton> or <CAUserCard>, it consults the CelerisAdminResolver to determine the source package. The plugin then inserts the corresponding import:

import { NButton } from '@celeris/ca-components'
import { CAUserCard } from '@celeris/components'

Developers can use components directly in templates without manual imports:

<template>
  <NButton type="primary">Click me</NButton>
  <CAUserCard :user="user" />
</template>

TypeScript Integration

The auto-import system maintains type safety through automatically generated declaration files. During the build process, the plugins emit:

• apps/admin/autoResolver/auto-imports.d.ts – Contains type definitions for auto-imported APIs and composables
• apps/admin/autoResolver/components.d.ts – Registers type definitions for auto-imported Vue components

These declaration files ensure that IDEs and the TypeScript compiler recognize symbols that aren't explicitly imported in the source code. This prevents "Cannot find name" errors while preserving full IntelliSense functionality.

Vite Pipeline Integration

Both plugins are instantiated within the configVitePlugins function located in packages/shared/vite/src/plugins/index.ts. This central registration point pushes the plugins into Vite's plugin array (lines 41-50), ensuring they execute early in the transformation pipeline.

This integration guarantees that auto-import functionality is active across the entire monorepo, from development server startup through production builds.

Summary

• Celeris Web uses unplugin-auto-import to inject imports for Vue APIs, vue-router, and internal composables from @celeris/hooks without manual import statements.
• The CelerisAdminResolver in unplugin-vue-components maps N* and CA* prefixed components to @celeris/ca-components and @celeris/components respectively.
• AST transformation occurs at build-time, rewriting source files to include necessary imports while preserving the original developer experience.
• TypeScript declarations are auto-generated in autoResolver/auto-imports.d.ts and autoResolver/components.d.ts to maintain type safety.
• Plugin registration is centralized in packages/shared/vite/src/plugins/index.ts via the configVitePlugins function.

Frequently Asked Questions

How does Celeris Web handle TypeScript types for auto-imported components?

The unplugin-vue-components plugin generates apps/admin/autoResolver/components.d.ts during the build process. This declaration file contains type definitions for all components resolved by the CelerisAdminResolver, ensuring TypeScript recognizes component tags like <NButton> or <CAUserCard> even when no explicit import statement exists in the source file.

What naming conventions trigger automatic component imports in Celeris Web?

According to the CelerisAdminResolver implementation in packages/shared/vite/src/plugins/unpluginVueComponets.ts, components prefixed with N or n- automatically resolve to @celeris/ca-components (Naive UI), while components prefixed with CA or ca- resolve to @celeris/components. These patterns allow the plugin to map template tags to their source packages without explicit configuration.

Can developers use auto-imported APIs in plain TypeScript files outside of Vue components?

Yes. The unplugin-auto-import configuration in packages/shared/vite/src/plugins/unpluginAutoImport.ts includes directories like src/composables and src/store in its scanning paths. This allows composables and utilities defined in these directories to be auto-imported into any TypeScript or Vue file within the project, not just component templates.

Where are the auto-import plugins registered in the Vite configuration?

Both plugins are instantiated inside the configVitePlugins function in packages/shared/vite/src/plugins/index.ts (lines 41-50). This centralized registration pushes the plugins into Vite's plugin array, ensuring they run early in the build pipeline and apply to all packages in the monorepo.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}