@douyinfe/semi-vite-plugin

A vite plugin for Semi Design to custom theme, replace prefix and so on.

Introduction

The plugin is designed for Semi Design with Vite, providing two major abilities:

• Custom theme
• Replace prefix of CSS selector

Note: The plugin detects Semi related dependencies by package path. It supports both @douyinfe/semi-ui and version-suffixed packages like @douyinfe/semi-ui-19 (also for semi-icons).

Usage

Install

Install @douyinfe/semi-vite-plugin as a development dependency:

npm install --save-dev @douyinfe/semi-vite-plugin
# or
yarn add --dev @douyinfe/semi-vite-plugin
# or
pnpm add -D @douyinfe/semi-vite-plugin

Custom theme

Semi Design uses Scss variables to extract thousands of Design Tokens. You can replace those tokens through this plugin to achieve theme customization. More info

You can custom theme through three ways:

• npm package generated by Semi DSM
• Local Scss file in your project
• Pass key-value pair parameters to plugin

Priority from low to high.

Through npm package

After finishing the customization on Semi Design System, Semi DSM will generate an npm package for you, then use it like this:

// vite.config.ts
import { defineConfig } from 'vite';
import semiTheming from '@douyinfe/semi-vite-plugin';

export default defineConfig({
    plugins: [
        semiTheming({
            theme: '@semi-bot/semi-theme-yours',
        }),
    ],
});

Through local Scss file

You can check which tokens can be customized on the Semi Website.

Step 1: add a local file

// local.scss
$font-size-small: 16px;

Step 2: config vite

// vite.config.ts
import path from 'path';
import { defineConfig } from 'vite';
import semiTheming from '@douyinfe/semi-vite-plugin';

export default defineConfig({
    plugins: [
        semiTheming({
            include: path.resolve(__dirname, 'local.scss'),
        }),
    ],
});

Through parameters

// vite.config.ts
import { defineConfig } from 'vite';
import semiTheming from '@douyinfe/semi-vite-plugin';

export default defineConfig({
    plugins: [
        semiTheming({
            variables: {
                '$font-size-small': '16px',
            },
        }),
    ],
});

Replace prefix of CSS selector

The CSS selectors used by Semi Design are prefixed with semi by default (e.g. .semi-button). You can replace the prefix through this plugin:

// vite.config.ts
import { defineConfig } from 'vite';
import semiTheming from '@douyinfe/semi-vite-plugin';

export default defineConfig({
    plugins: [
        semiTheming({
            prefixCls: 'custom',
        }),
    ],
});

Then you get the replaced CSS selectors (e.g. .custom-button).

Wrap output styles with CSS layer

// vite.config.ts
import { defineConfig } from 'vite';
import semiTheming from '@douyinfe/semi-vite-plugin';

export default defineConfig({
    plugins: [
        semiTheming({
            cssLayer: true,
        }),
    ],
});

API

semiTheming(options)

How it works

1. CSS → SCSS rewrite: Intercepts requests to @douyinfe/semi-(ui|icons|foundation)/lib/**/*.css, switches the suffix to .scss and reads the original Sass source.
2. Theme injection: Injects the theme index.scss / global.scss / animation.scss / local.scss / user-provided variables and include files, plus $prefix and (optional) @layer semi { ... } wrapper.
3. Sass compilation: Compiles the assembled Sass source with sass.compileString, resolving ~package/... imports against the node_modules tree of the original .scss file.
4. Prefix patch: For files matching @douyinfe/semi-*/.../env.js, rewrites BASE_CLASS_PREFIX constant to the configured prefixCls. To make the same replacement work for Vite's dev-mode dep pre-bundle (.vite/deps), an esbuild plugin is registered via optimizeDeps.esbuildOptions.plugins to rewrite the env modules at pre-bundle time as well.
5. omitCss: Optionally comments out .css imports inside Semi packages so they don't reach the bundler.

FAQ

Why are classnames still semi-* in vite dev?

Vite pre-bundles node_modules packages into .vite/deps using esbuild (or Rolldown in Vite 8+). When prefixCls is set, this plugin injects an esbuild plugin to rewrite the relevant env.js files inside the pre-bundle. If you previously started vite once without the plugin (or with a different prefixCls), you may have a stale .vite/deps cache. Stop the dev server and run rm -rf node_modules/.vite to force a clean re-bundle.

Vite 8 prints a deprecation warning about optimizeDeps.esbuildOptions

Vite 8 switched to Rolldown for dep pre-bundling and now prefers optimizeDeps.rolldownOptions. The plugin still uses optimizeDeps.esbuildOptions for broad compatibility with Vite ≥3; Rolldown keeps an esbuild-compatible shim, so the warning is harmless and the prefix rewrite still works correctly.

Related

• Semi Design
• @douyinfe/semi-webpack-plugin
• @douyinfe/semi-rspack-plugin