Version Migration

v1.0.0 ​

v1.0.0 is the first stable release. It contains several breaking changes, mostly removals of long-deprecated options. Most blogs need no changes; review the items below if you used these features.

Mermaid → valaxy-addon-mermaid ​

Starting with Valaxy 1.0.0-rc.16, Mermaid has moved to the optional official valaxy-addon-mermaid package. Install and enable it only if your site uses diagrams. Existing Markdown fences remain unchanged.

bash
pnpm add valaxy@latest valaxy-addon-mermaid
ts
// valaxy.config.ts
import { defineValaxyConfig } from 'valaxy'
import { addonMermaid } from 'valaxy-addon-mermaid'

export default defineValaxyConfig({
  addons: [addonMermaid()],
})

Without the addon, actual Mermaid fences or legacy setup/mermaid.ts trigger an actionable migration notice. Fences stay readable as source. Existing setup files continue to work after enabling the addon; import defineMermaidSetup, MermaidOptions, and MermaidSetup from the addon.

Mermaid addon

Node.js: minimum version is now >=22.12.0 ​

Valaxy now requires Node.js >=22.12.0 (previously ^18 || >=20). This comes from unplugin-vue-markdown@32 (which requires Node >=22) combined with Vite 8 (^20.19.0 || >=22.12.0) — on the Node 22 line the minimum is 22.12.0. Node 18 and 20 are no longer supported. Upgrade your local, CI, and deploy environments before updating (see #710).

SSG: legacy vite-ssg engine removed ​

The JSDOM-based vite-ssg SSG engine has been removed (it was broken under pnpm; see #706). There is now a single built-in Valaxy SSG engine.

  • The --ssg-engine CLI flag and the build.ssg.engine config option are gone — just run valaxy build --ssg.
  • vite.ssgOptions is still supported but now follows the ValaxySSGOptions shape: concurrency, includedRoutes, includeAllRoutes, onBeforePageRender, onPageRendered, onFinished. The vite-ssg-only options (dirStyle, beastiesOptions, formatting, script) no longer exist.
  • Critical CSS inlining (beasties) is removed. Flash-of-unstyled-content is handled by the FOUC guard instead (build.foucGuard).
  • For directory-style output (/foo/index.html), use a directory index page (pages/foo/index.md) instead of the old dirStyle: 'nested' option.

Music player moved to valaxy-addon-meting ​

The built-in aplayer: true frontmatter switch no longer loads the music player. Install and enable the addon:

ts
// valaxy.config.ts
import { addonMeting } from 'valaxy-addon-meting'

export default defineValaxyConfig({
  addons: [addonMeting()],
})

<meting-js> usage in Markdown is otherwise unchanged. See Music Player.

Config & frontmatter removals ​

  • ignoreDeadLinks at the config root → use build.ignoreDeadLinks.
  • unocssPresets.uno → use unocssPresets.wind4 (it was already a no-op since the wind3→wind4 migration).
  • Frontmatter color (title color) was removed from core types. It is a theme concern — valaxy-theme-yun still reads it at runtime; prefer pageTitleClass / postTitleClass.

SSR globals ​

If a theme or addon relied on the old engine’s JSDOM (which silently provided window / document / navigator during SSR), guard those accesses — the current engine renders pure strings with no DOM. See SSR Compatibility.

v0.21.0 ​

Import Common Styles Yourself ​

Theme developers need to import the common styles valaxy/client/styles/common/index.scss themselves.

See Import Default Styles.

Contributors