@aleph-alpha/config-vite

Shared Vite configuration and plugins for Aleph Alpha projects.

Installation

pnpm add -D @aleph-alpha/config-vite vite @vitejs/plugin-vue

vite and @vitejs/plugin-vue are required peer dependencies. The plugins for JSX, UnoCSS, and Vue DevTools are optional peers and only need to be installed when the corresponding feature is enabled.

Usage

Shared Vue Config

Use defineAlephVueConfig to apply the shared Vue Vite defaults in a consumer project. By default it only registers the Vue plugin and the @ → src alias — every other integration is opt-in.

import { defineAlephVueConfig } from '@aleph-alpha/config-vite';

export default defineAlephVueConfig();

Project-specific Vite config can be passed as usual and is merged with the defaults.

import { defineAlephVueConfig } from '@aleph-alpha/config-vite';

export default defineAlephVueConfig({
  base: '/app/',
  build: {
    sourcemap: true,
  },
});

The callback form is also supported for env-dependent config (matches Vite's defineConfig((env) => ...)):

import { defineAlephVueConfig } from '@aleph-alpha/config-vite';

export default defineAlephVueConfig(({ mode }) => ({
  root: import.meta.dirname,
  unoCss: true,
  build: {
    sourcemap: mode !== 'production',
  },
}));

Opt-in features:

import { defineAlephVueConfig } from '@aleph-alpha/config-vite';

export default defineAlephVueConfig({
  unoCss: true,
  vueJsx: true,
  devTools: true,
  testDefaults: true,
  extractCss: {
    baseUrl: '/app/',
    addPreload: true,
  },
});

Pass options to the Vue or Vue JSX plugin directly:

export default defineAlephVueConfig({
  vue: {
    template: {
      compilerOptions: {
        isCustomElement: (tag) => tag.startsWith('ion-'),
      },
    },
  },
  vueJsx: { optimize: true },
});

The shared Vue config options are:

• vue?: boolean | VuePluginOptions - Toggle the Vue plugin or pass options to it (default: true)
• vueJsx?: boolean | VueJsxPluginOptions - Enable Vue JSX/TSX, optionally with options (default: false)
• unoCss?: boolean - Enable UnoCSS (default: false)
• devTools?: boolean - Enable Vue DevTools (default: false)
• srcAlias?: boolean | string - Alias @ to <root>/src, or a custom path resolved relative to the Vite root (default: true)
• extractCss?: boolean | ExtractCssOptions - Enable the CSS extraction plugin (default: false)
• testDefaults?: boolean - Apply shared Vitest defaults (jsdom, globals, v8 coverage). Override fields via test (default: false)

The srcAlias path is resolved against the Vite root if you set one (e.g. root: import.meta.dirname in Nx apps), otherwise against process.cwd().

Extract CSS Plugin

The extractCssPlugin allows you to split CSS into separate chunks for better performance optimization. When HTML assets are part of the Vite build, the plugin injects links for the generated CSS chunks into the HTML head. Only links for CSS chunks that were actually generated are injected.

import { defineConfig } from 'vite';
import { extractCssPlugin } from '@aleph-alpha/config-vite';

export default defineConfig({
  plugins: [
    extractCssPlugin({
      splitIcons: true,
      splitFonts: true,
      chunkNameIcons: 'icons',
      chunkNameFonts: 'fonts',
      baseUrl: '/app/',
      outputDir: 'assets',
      addPreload: true,
      onExtract: (files) => {
        console.log('Extracted CSS files:', files);
      },
    }),
  ],
});

Available Plugins

• extractCssPlugin - Plugin for extracting and splitting CSS chunks (icons, fonts, etc.)

Available Configs

• defineAlephVueConfig - Shared Vite config preset for Vue projects

Plugin Options

ExtractCssOptions

• splitIcons?: boolean - Whether to split SVG icons into separate CSS chunk (default: true)
• splitFonts?: boolean - Whether to split font-face declarations into separate CSS chunk (default: true)
• chunkNameIcons?: string - Name for the icons CSS chunk (default: 'icons')
• chunkNameFonts?: string - Name for the fonts CSS chunk (default: 'fonts')
• baseUrl?: string - Base URL for CSS chunks (default: '/'). Examples: /app/, https://cdn.example.com/
• addPreload?: boolean - Whether to add preload links for generated CSS chunks in HTML head (default: false)
• outputDir?: string - Output directory for CSS chunks (default: 'assets')
• onExtract?: (files: string[]) => void - Callback function called after CSS extraction

Base URL Configuration

The baseUrl option allows you to specify a custom base URL for your CSS chunks. This is useful when:

• Deploying to a subdirectory (e.g., /app/)
• Using a CDN for static assets
• Serving assets from a different domain

Examples

Subdirectory deployment:

extractCssPlugin({
  baseUrl: '/app/',
  // Will generate: <link rel="stylesheet" href="/app/assets/fonts.css">
});

CDN deployment:

extractCssPlugin({
  baseUrl: 'https://cdn.example.com/',
  // Will generate: <link rel="stylesheet" href="https://cdn.example.com/assets/fonts.css">
});

Root deployment (default):

extractCssPlugin({
  baseUrl: '/', // or omit the option
  // Will generate: <link rel="stylesheet" href="/assets/fonts.css">
});

Development

# Install dependencies
pnpm install

This package is built with TypeScript and publishes the generated dist output.