# How Celeris Web's Auto-Import System Works: Unplugin Architecture Deep Dive > Discover how Celeris Web's auto-import system leverages unplugin to inject import statements for APIs and components, streamlining development across your monorepo. - Repository: [Kirk Lin/celeris-web](https://github.com/kirklin/celeris-web) - Tags: internals - Published: 2026-03-05 --- **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`](https://github.com/kirklin/celeris-web/blob/main/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`](https://github.com/kirklin/celeris-web/blob/main/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`](https://github.com/kirklin/celeris-web/blob/main/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`](https://github.com/kirklin/celeris-web/blob/main/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: ```typescript 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 `` or ``, it consults the `CelerisAdminResolver` to determine the source package. The plugin then inserts the corresponding import: ```typescript import { NButton } from '@celeris/ca-components' import { CAUserCard } from '@celeris/components' ``` Developers can use components directly in templates without manual imports: ```vue ``` ## 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`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/autoResolver/auto-imports.d.ts) – Contains type definitions for auto-imported APIs and composables - [`apps/admin/autoResolver/components.d.ts`](https://github.com/kirklin/celeris-web/blob/main/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`](https://github.com/kirklin/celeris-web/blob/main/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`](https://github.com/kirklin/celeris-web/blob/main/autoResolver/auto-imports.d.ts) and [`autoResolver/components.d.ts`](https://github.com/kirklin/celeris-web/blob/main/autoResolver/components.d.ts) to maintain type safety. - **Plugin registration is centralized** in [`packages/shared/vite/src/plugins/index.ts`](https://github.com/kirklin/celeris-web/blob/main/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`](https://github.com/kirklin/celeris-web/blob/main/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 `` or `` 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`](https://github.com/kirklin/celeris-web/blob/main/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`](https://github.com/kirklin/celeris-web/blob/main/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`](https://github.com/kirklin/celeris-web/blob/main/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.