# How Vite Configuration Is Managed and Applied via the @celeris/vite Package

> Learn how @celeris/vite manages Vite configuration by merging defaults with your overrides for efficient build-time application.

- Repository: [Kirk Lin/celeris-web](https://github.com/kirklin/celeris-web)
- Tags: how-to-guide
- Published: 2026-03-05

---

**The @celeris/vite package centralizes Vite configuration by exporting a `createViteConfig` helper that merges default application settings with user-provided overrides, returning a Vite `defineConfig` wrapper consumed at build-time.**

The Celeris monorepo uses the **@celeris/vite** package to standardize build tooling across multiple frontend applications. This shared package eliminates configuration duplication by providing a single entry point—`createViteConfig`—that generates a complete Vite **UserConfig** while still allowing per-project customization. Located at `packages/shared/vite/`, it serves as the single source of truth for Vite configuration throughout the repository.

## Core Architecture of @celeris/vite

### The createViteConfig Entry Point

The primary API lives in [`packages/shared/vite/src/config/index.ts`](https://github.com/kirklin/celeris-web/blob/main/packages/shared/vite/src/config/index.ts). This file exposes the `createViteConfig` function and a `mergeConfigs` utility responsible for deep-merging configuration objects.

```typescript
export async function createViteConfig(applicationViteConfigOptions: ApplicationViteConfigOptions = {}) {
  const { overrides = {} } = applicationViteConfigOptions;
  const root = process.cwd();
  return defineConfig(async ({ command, mode }) => {
    return mergeConfigs([overrides, await createApplicationViteConfig(command, mode, root)]);
  });
}

```

The function accepts an optional `ApplicationViteConfigOptions` object containing an `overrides` property. It captures the current working directory via `process.cwd()` to establish the project root, then returns a Vite `defineConfig` wrapper that receives the `command` and `mode` at build-time.

### Default Application Configuration

The heavy lifting occurs within `packages/shared/vite/src/configs/application/` (implementation files). The `createApplicationViteConfig` function assembles the baseline configuration by:

- Registering framework plugins (Vue, JSX, PWA, visualizer)
- Configuring path aliases and resolve settings
- Setting environment variable handling
- Defining the default **output directory** as `"dist"`
- Adjusting settings based on the current `command` (`serve` vs `build`) and `mode` (`development`, `production`)

This baseline is then merged with any user-provided overrides before being returned to Vite.

### Centralized Constants

Shared values are defined in [`packages/shared/vite/src/constants.ts`](https://github.com/kirklin/celeris-web/blob/main/packages/shared/vite/src/constants.ts) to ensure consistency across the monorepo:

```typescript
export const GLOB_CONFIG_FILE_NAME = "_app.config.js";
export const OUTPUT_DIR = "dist";
export const APP_NAME = "Celeris_Web";

```

These constants are referenced throughout the configuration logic, guaranteeing uniform build artifacts and application metadata.

## Build-Time Configuration Flow

When Vite initializes, the @celeris/vite package orchestrates configuration resolution through the following steps:

1. **Entry Point Resolution**: Vite reads the project's configuration file (e.g., `apps/admin/vite.config.mts`), which imports and calls `createViteConfig()` from `@celeris/vite`.
2. **Root Capture**: The helper immediately captures `process.cwd()` as the project root.
3. **Context Injection**: Vite invokes the callback provided to `defineConfig`, supplying the current `command` (`serve` or `build`) and `mode`.
4. **Baseline Generation**: `createApplicationViteConfig(command, mode, root)` constructs the default configuration, including plugins, server settings, and the `dist` output folder.
5. **Override Application**: The `mergeConfigs` utility performs a deep merge between the baseline and the user's `overrides` object.
6. **Final Resolution**: The merged configuration object is returned to Vite, which proceeds with the standard development server or production build workflow.

## Practical Usage Examples

### Default Setup Without Overrides

Projects adopt the shared defaults by importing the helper and exporting its result:

```typescript
// apps/admin/vite.config.mts
import { createViteConfig } from "@celeris/vite";

export default createViteConfig();

```

This single line provides the complete default application configuration, including all standard plugins and optimizations.

### Adding Custom Resolve Aliases

Per-project customization is achieved via the `overrides` option:

```typescript
// apps/admin/vite.config.mts
import { createViteConfig } from "@celeris/vite";

export default createViteConfig({
  overrides: {
    resolve: {
      alias: {
        "@my-lib": "/src/lib/custom.ts",
      },
    },
  },
});

```

The merge utility ensures custom aliases are combined with the default alias map rather than replacing it.

### Modifying Build Output Directories

Override the default `"dist"` output location by providing a `build` configuration object:

```typescript
// apps/admin/vite.config.mts
import { createViteConfig } from "@celeris/vite";

export default createViteConfig({
  overrides: {
    build: {
      outDir: "public/build",
    },
  },
});

```

This pattern guarantees that only the specific delta required is defined in consumer projects, maintaining the **single source of truth** established in the shared package.

## Summary

- **Single Entry Point**: The `createViteConfig` function in [`packages/shared/vite/src/config/index.ts`](https://github.com/kirklin/celeris-web/blob/main/packages/shared/vite/src/config/index.ts) serves as the unified interface for all Vite configuration in the Celeris monorepo.
- **Merge Strategy**: User-provided `overrides` are deep-merged with default application configurations generated by `createApplicationViteConfig`.
- **Key Files**: Core logic resides in `packages/shared/vite/src/configs/application/`, constants in [`packages/shared/vite/src/constants.ts`](https://github.com/kirklin/celeris-web/blob/main/packages/shared/vite/src/constants.ts), and consumption examples in `apps/admin/vite.config.mts`.
- **Flexibility**: Developers can override any Vite setting (aliases, output directories, plugins) while maintaining baseline consistency across the monorepo.

## Frequently Asked Questions

### Where is the `createViteConfig` function defined?

The `createViteConfig` function is defined in [`packages/shared/vite/src/config/index.ts`](https://github.com/kirklin/celeris-web/blob/main/packages/shared/vite/src/config/index.ts). It serves as the main entry point that consumer projects import to generate their Vite configuration.

### How do I override the default output directory when using @celeris/vite?

Pass an `overrides` object with a `build.outDir` property to `createViteConfig`. The default output directory is `"dist"` as specified in [`packages/shared/vite/src/constants.ts`](https://github.com/kirklin/celeris-web/blob/main/packages/shared/vite/src/constants.ts), but you can override it to any path required by your deployment pipeline.

### Can I add custom Vite plugins while using the shared configuration?

Yes. Include your custom plugins in the `overrides.plugins` array when calling `createViteConfig`. The internal `mergeConfigs` utility combines them with the default application plugins (Vue, JSX, PWA, etc.) rather than replacing the entire plugin chain.

### What happens if I call `createViteConfig()` without any arguments?

If no arguments are provided, the function returns the default configuration generated by `createApplicationViteConfig`, which includes standard plugins, path aliases, environment handling, and the `"dist"` build output directory defined in the package constants.