Migrating from v1 to v2

This guide helps you smoothly migrate from @fuxishi/vitepress-theme v1.x (based on VitePress 1.x) to v2.x (based on VitePress 2.0).

Prerequisites

• VitePress upgraded to 2.0+
• Node.js >=18

npm install vitepress@latest

Breaking Changes

1. Config API Update

v2 uses defineConfig<ThemeConfig>() instead of the deprecated defineConfigWithTheme, and composes custom config via intersection types.

v1 (deprecated):

import { defineConfigWithTheme } from "vitepress"
import fxConfig from "@fuxishi/vitepress-theme/config"
import type { FxThemeConfig } from "@fuxishi/vitepress-theme/config"

export default defineConfigWithTheme<FxThemeConfig>({
  extends: fxConfig,
  // ...
})

v2:

import { defineConfig } from "vitepress"
import type { DefaultTheme } from "vitepress"
import fxConfig from "@fuxishi/vitepress-theme/config"
import type { FxThemeCustomConfig } from "@fuxishi/vitepress-theme"

type ThemeConfig = DefaultTheme.Config & FxThemeCustomConfig

export default defineConfig<ThemeConfig>({
  extends: fxConfig,
  // ...
})

Key differences:

Item	v1	v2
Config function	defineConfigWithTheme	defineConfig<ThemeConfig>()
Type import	FxThemeConfig from .../config	FxThemeCustomConfig from @fuxishi/vitepress-theme
Type composition	Directly extends DefaultTheme.Config	DefaultTheme.Config & FxThemeCustomConfig
Extra import	None	Need to import DefaultTheme

2. Theme Registration (No Change)

Theme registration remains the same:

import FxTheme from "@fuxishi/vitepress-theme"
import "@fuxishi/vitepress-theme/style.css"

export default FxTheme

3. Enhanced Code Block Beam Border

In v2, the dark mode code block beam border effect now also supports the entire code-group (::: code-group) container. When hovering, the whole code group displays the rotating beam border.

Migration Steps

Step 1: Upgrade Dependencies

npm install @fuxishi/vitepress-theme@latest
npm install vitepress@latest

Step 2: Update Config File

Modify .vitepress/config.mts following the v2 pattern shown above.

Full example:

import { defineConfig } from "vitepress"
import type { DefaultTheme } from "vitepress"
import fxConfig from "@fuxishi/vitepress-theme/config"
import type { FxThemeCustomConfig } from "@fuxishi/vitepress-theme"

type ThemeConfig = DefaultTheme.Config & FxThemeCustomConfig

export default defineConfig<ThemeConfig>({
  extends: fxConfig,
  lang: "en",
  title: "My Docs",
  themeConfig: {
    // Your existing config remains unchanged
    nav: [{ text: "Guide", link: "/guide/" }],
    sidebar: {
      "/guide/": [{ text: "Getting Started", link: "/guide/" }],
    },
    // All config options below are fully compatible with v1 — no changes needed
    musicBall: { enable: true, src: "/music/song.mp3" },
    confetti: true,
    heroImageColor: true,
    smoothScroll: true,
    codeBlockFold: { lines: 10 },
  },
})

Step 3: Verify

Start the dev server to confirm everything works:

npx vitepress dev

What Stays the Same

The following config options and behaviors are fully compatible in v2 — no changes required:

• Theme registration — import FxTheme + import "style.css" unchanged
• Music ball config — all musicBall fields unchanged
• Confetti config — all confetti modes unchanged
• Hero image color — heroImageColor behavior unchanged
• Smooth scroll — smoothScroll behavior unchanged
• Code block fold — all codeBlockFold fields unchanged
• CSS variable overrides — all --fx-beam-c1, --fx-beam-c2, music ball variables unchanged
• Custom CSS — all custom styles unchanged

FAQ

TypeScript type errors

Make sure your tsconfig.json has correct VitePress path configuration, and you're using the type ThemeConfig = DefaultTheme.Config & FxThemeCustomConfig intersection type instead of FxThemeConfig extends DefaultTheme.Config.

defineConfigWithTheme not found

VitePress 2.0 has deprecated defineConfigWithTheme. Use defineConfig<ThemeConfig>() instead.

NoInfer errors

NoInfer is a built-in utility type in TypeScript 5.4+. It does not need to be imported from vitepress. If you encounter this error, upgrade TypeScript to 5.4 or later.