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

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. This file exposes the createViteConfig function and a mergeConfigs utility responsible for deep-merging configuration objects.

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 to ensure consistency across the monorepo:

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:

// 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:

// 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:

// 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 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, 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. 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, 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.

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