valaxy

name: valaxy description: > Valaxy static blog framework built with Vue 3, Vite, and pnpm workspaces. Use when working with Valaxy projects: (1) creating or configuring Valaxy blog sites (site.config.ts, valaxy.config.ts), (2) writing blog posts with frontmatter, (3) developing Valaxy themes (valaxy-theme-), (4) developing Valaxy addons (valaxy-addon-), (5) customizing components/layouts/styles, (6) working with the Valaxy monorepo core framework, (7) debugging Valaxy builds or dev server, (8) deploying Valaxy sites. Triggers on: valaxy.config.ts, site.config.ts, theme.config.ts, defineValaxyConfig, defineSiteConfig, defineThemeConfig, defineTheme, defineAddon, valaxy-theme-, valaxy-addon-, pages/posts/, ValaxyMain, useSiteConfig, useFrontmatter, #valaxy/config.

Next-generation static blog framework: Vue 3 + Vite + UnoCSS + file-based routing + markdown-it.

Quick Reference

pnpm create valaxy          # scaffold new site
pnpm i                      # MUST use pnpm
pnpm dev                    # dev server at localhost:4859
pnpm build                  # SSG build to dist/

Two config files:

site.config.ts — site metadata (title, author, social, search, comments) via defineSiteConfig()
valaxy.config.ts — framework config (theme, addons, markdown, vite) via defineValaxyConfig<ThemeConfig>()
Optional theme.config.ts — theme-specific via defineThemeConfig()

Posts go in pages/posts/*.md. Frontmatter controls title, date, tags, categories, cover, draft, encryption, layout, etc.

Key Patterns

Config Merging

Config sources merge via defu (user wins): Default → Theme → Addons → User.

File Resolution (Roots System)

roots = [clientRoot, themeRoot, ...addonRoots, userRoot]

User components/layouts/styles override theme which overrides core — by filename matching.

Routing

File-based via vue-router/vite. Files in pages/ become routes. Layout auto-assigned:

pages/posts/** → post layout
pages/tags/** → tags layout
pages/categories/** → categories layout

Override with layout: xxx in frontmatter.

Collections

Define in pages/collections/{name}/index.ts using defineCollection():

import { defineCollection } from 'valaxy'

export default defineCollection({
  key: 'hamster',
  title: 'Hamster Stories',
  items: [
    { title: 'Chapter 1', key: '1' },
  ],
})

i18n

CSS-based bilingual: ::: zh-CN / ::: en containers in markdown
File-based: locales/*.yml
Frontmatter: title: { en: 'Title', 'zh-CN': '标题' }
Tags: $locale:tag.notes syntax

Custom Styles

Create styles/index.ts (or .scss/.css) — auto-loaded. Override CSS vars for theming.

Custom Components

Place .vue files in components/ — auto-registered, overrides theme/core components by name.

Monorepo Development

When working on the Valaxy core framework itself:

pnpm i                     # install all workspace deps
pnpm run build             # build core: utils → valaxy → devtools
pnpm dev:lib               # watch core packages
pnpm demo                  # run demo site
pnpm docs:dev              # run docs site
pnpm test                  # unit tests (vitest)
pnpm e2e                   # E2E tests (playwright)
pnpm lint                  # eslint
pnpm typecheck             # type check

Repository URL Normalization

When displaying repository URLs from package.json, import and use normalizeRepositoryUrl() from @valaxyjs/utils to remove the git+ prefix.

References

Framework architecture, virtual modules, composables, components: Read references/architecture.md
Theme/addon development, post frontmatter, addon gallery: Read references/theme-addon-dev.md