How to Add UnoCSS Preset Configurations to Celeris Web: A Complete Guide

To add new UnoCSS preset configurations to Celeris Web, install your desired preset package and register it in the centralized packages/web/styles/uno.config.ts file; the shared Vite plugin automatically propagates these changes across the entire monorepo without requiring additional configuration.

Celeris Web uses a centralized architecture for styling that makes extending utility-first CSS straightforward. All UnoCSS preset configurations live in a single shared configuration file, which is then consumed by the custom Vite plugin used throughout the monorepo. This design ensures consistency while allowing rapid customization of the atomic CSS pipeline.

Understanding the Centralized UnoCSS Architecture

The Central Configuration File

In packages/web/styles/uno.config.ts, Celeris Web maintains the single source of truth for all UnoCSS settings. This file exports a shareConfig object that defines presets, shortcuts, theme extensions, and transformers. Any modification to this file immediately affects the global styling pipeline because the Vite plugin does not maintain a separate configuration—it imports and spreads this shared object directly.

How the Vite Plugin Consumes the Configuration

The Vite plugin located at packages/shared/vite/src/plugins/unocss.ts imports this shared configuration and spreads it into the UnoCSS Vite plugin initialization. The plugin uses the spread operator (...unoShareConfig) to inject the entire configuration object, which means any preset added to the central file automatically becomes available in all applications consuming the shared Vite configuration. There is no need to touch the plugin code when adding or removing presets.

Step-by-Step Guide to Adding UnoCSS Preset Configurations

1. Install the Preset Package

Use your package manager to add the preset as a dev dependency. For example, to add the typography preset:

pnpm add -D unocss-preset-typography

2. Import and Register the Preset

Open packages/web/styles/uno.config.ts and import your preset at the top of the file. Then add it to the presets array within the shareConfig object:

// packages/web/styles/uno.config.ts
import type { UserConfig } from "unocss";
import {
  presetAttributify,
  presetIcons,
  presetUno,
  transformerDirectives,
  transformerVariantGroup,
} from "unocss";
import presetChinese, { chineseTypography } from "unocss-preset-chinese";
import presetEase from "unocss-preset-ease";

// Import your new preset
import presetTypography from "unocss-preset-typography";

const shareConfig: UserConfig = {
  content: {
    pipeline: { exclude: ["node_modules", ".git", "dist"] },
  },
  presets: [
    presetUno({ dark: "class" }),
    presetAttributify(),
    chineseTypography(),
    presetChinese({ chineseType: "simplified" }),
    presetEase(),
    // Add your preset here
    presetTypography(),
    presetIcons({ scale: 1.2, warn: true }),
  ],
  // shortcuts, theme, and transformers remain unchanged
};

export default shareConfig;

3. Consider Preset Ordering

The order of presets in the array matters for theme overrides and specificity. Place presets that define base styles earlier in the array, and specialized or overriding presets later. For example, if a new preset redefines color scales, position it after presetUno but before presetIcons to ensure proper inheritance.

4. Verify Your Configuration

Start the development server to verify the preset loads correctly:

pnpm dev

Vite's hot module replacement will detect the configuration changes in uno.config.ts and apply them across all consuming packages. All components in the repository will now have access to the classes and utilities provided by the new preset.

Extending Presets with Custom Shortcuts and Themes

Many presets support additional customization through the shared configuration. You can extend the shortcuts or theme properties in the same uno.config.ts file to override preset defaults or add complementary utility classes:

const shareConfig: UserConfig = {
  // ... presets array
  shortcuts: {
    // Custom shortcuts that work alongside your new preset
    'btn': 'py-2 px-4 font-semibold rounded-lg',
  },
  theme: {
    colors: {
      primary: '#3b82f6',
    }
  }
};

Summary

• Centralized configuration: All UnoCSS preset configurations reside in packages/web/styles/uno.config.ts.
• Automatic propagation: The Vite plugin at packages/shared/vite/src/plugins/unocss.ts spreads the shared config using ...unoShareConfig, eliminating the need to modify build tooling.
• Simple workflow: Install the preset, import it into uno.config.ts, add it to the presets array, and restart the dev server.
• Order matters: Arrange presets in the array based on priority and override requirements to ensure correct theme inheritance.

Frequently Asked Questions

Where is the main UnoCSS configuration file located in Celeris Web?

The primary configuration file is located at packages/web/styles/uno.config.ts. This file exports the shareConfig object that defines all presets, transformers, shortcuts, and theme customizations used across the monorepo.

Do I need to modify the Vite plugin when adding a new preset?

No. The Vite plugin in packages/shared/vite/src/plugins/unocss.ts imports and spreads the shared configuration using ...unoShareConfig. As long as you add your preset to the central uno.config.ts file, the changes automatically propagate to all applications without touching the plugin source.

Can I add multiple presets at once?

Yes. You can import and add multiple presets to the presets array in uno.config.ts. Ensure you consider the order of presets, as later presets may override theme values or shortcuts defined by earlier ones.

How do presets interact with existing shortcuts and theme values?

Presets integrate seamlessly with existing configuration. You can define additional shortcuts and theme properties in the same shareConfig object, and these will be merged with the preset defaults. Later presets in the array can override earlier theme definitions, allowing for progressive customization of the design system.

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