Getting Started

⚠️ Work in Progress: Vize is under active development and is not yet ready for production use. APIs and package boundaries may change without notice.

What is Vize?

Vize (/viːz/) is an unofficial Vue.js toolchain written in Rust. The workspace contains shared building blocks for:

This guide recommends Vite+ (vp) for JavaScript package management and project commands. It keeps the install and exec flow consistent across package managers while still using the workspace's underlying tool.

If you do not have vp yet, install it once and open a new shell:

curl -fsSL https://vite.plus | bash

See the Vite+ docs and the Installing Dependencies guide for more.

What Vize Does

At a high level, Vize is split into a few reusable pipelines:

See Static Analysis for the lint and type-checking model, Rules for concrete rule output, and Configuration for shared config and compiler options.

Choose Your Entry Point

1. Vite Projects

Use the Vite plugin if you want native Vue compilation in an existing Vite project.

vp install -D @vizejs/vite-plugin

Install vize as a direct dependency only when you want to import shared config helpers from "vize" or run the npm CLI through vp exec vize.

// vite.config.ts
import { defineConfig } from "vite";
import vize from "@vizejs/vite-plugin";

export default defineConfig({
  plugins: [vize()],
});

Add compiler options in vize.config.ts when you want the same settings available to the npm CLI and plugin:

import { defineConfig } from "vize";

export default defineConfig({
  compiler: {
    sourceMap: true,
    vapor: false,
    customRenderer: false,
  },
  vite: {
    scanPatterns: ["src/**/*.vue"],
  },
});

2. Nuxt Projects

Use the Nuxt module when you want Vize to run inside Nuxt's own Vite pipeline.

vp install @vizejs/nuxt

Add the module to nuxt.config.ts:

export default defineNuxtConfig({
  modules: ["@vizejs/nuxt"],
  vize: {
    compiler: true,
  },
});

Run your Nuxt dev server as usual. The module registers @vizejs/vite-plugin for Vue SFC compilation while preserving Nuxt auto-imports, components, middleware, and SSR transforms.

See the Nuxt Integration guide for Musea setup and Nuxt-specific notes.

3. npm CLI + Shared Config

Use the vize npm package when you want shared config utilities and native CLI commands available in package scripts.

vp install -D vize
vp exec vize fmt --write src
vp exec vize lint --preset happy-path src
vp exec vize check src
vp exec vize build src
vp exec vize ready src

The npm vize check command uses the packaged NAPI checker and can emit Vue component declarations with --declaration --declaration-dir dist/types. Use the Rust CLI when you need the Corsa-backed project diagnostics path across Vue, TS, TSX, and .d.ts inputs.

Recommended package scripts:

{
  "scripts": {
    "vue:fmt": "vize fmt --write src",
    "vue:lint": "vize lint --preset happy-path src",
    "vue:check": "vize check src",
    "vue:ready": "vize ready src"
  }
}

4. Full Rust CLI

Use the Rust binary when you want the full native CLI today. For v1 alpha, the supported public channels are GitHub release binaries and the Nix entry point; the Rust CLI is not published through crates.io yet.

nix run github:ubugeeei/vize#vize -- --help

vize build src/**/*.vue
vize fmt --check src
vize lint --profile src
vize check --profile src
vize ready src
vize lsp

Native Type Checking

vize check is powered by vize_canon, which now leans on corsa-bind project sessions for native TypeScript diagnostics. Vize generates virtual TypeScript for Vue SFCs, asks Corsa for project-aware diagnostics, and then maps the results back onto the original .vue, .ts, .tsx, and .d.ts files.

This path is still maturing, so editor type checking remains an opt-in capability for now. The runtime stack is the @typescript/native-preview package, Corsa/corsa-bind is the API layer Vize talks to, and the executable installed by the TypeScript native preview is still commonly named tsgo. Use typeChecker.corsaPath or vize check --corsa-path /path/to/tsgo when you want to pin that runtime. typeChecker.tsgoPath remains a deprecated compatibility alias.

Useful type-checking commands:

vize check
vize check --tsconfig tsconfig.app.json
vize check --show-virtual-ts src/components/App.vue
vize check --declaration --declaration-dir dist/types

Shared vize.config.*

The npm CLI and @vizejs/vite-plugin share config discovery:

• vize.config.pkl

• vize.config.ts

• vize.config.js

• vize.config.mjs

• vize.config.json

TypeScript config:

import { defineConfig } from "vize";

export default defineConfig({
  compiler: {
    sourceMap: true,
    vapor: false,
    customRenderer: false,
  },
  linter: {
    preset: "opinionated",
  },
  typeChecker: {
    enabled: true,
    strict: true,
    corsaPath: "./node_modules/.bin/tsgo",
  },
  formatter: {
    printWidth: 100,
  },
  musea: {
    include: ["src/**/*.art.vue"],
    basePath: "/__musea__",
  },
  lsp: {
    lint: true,
    typecheck: false,
    editor: false,
    formatting: false,
  },
});

PKL config:

amends "node_modules/vize/pkl/vize.pkl"

linter {
  preset = "opinionated"
}

typeChecker {
  enabled = true
  strict = true
}

lsp {
  lint = true
  typecheck = false
  editor = false
  formatting = false
}

JSON config with schema:

{
  "$schema": "./node_modules/vize/schemas/vize.config.schema.json",
  "linter": {
    "preset": "opinionated"
  }
}

Packages

vp install -D @vizejs/vite-plugin
vp install @vizejs/native
vp install @vizejs/wasm
vp install @vizejs/unplugin
vp install @vizejs/rspack-plugin @rspack/core
vp install @vizejs/nuxt
vp install @vizejs/vite-plugin-musea
vp install @vizejs/musea-mcp-server
vp install -D oxlint oxlint-plugin-vize

Notes:

• @vizejs/vite-plugin is the recommended bundler integration today.

• @vizejs/unplugin and @vizejs/rspack-plugin are still experimental.

• @vizejs/native and @vizejs/wasm expose the Rust bindings directly.

• @vizejs/vite-plugin-musea provides the gallery and dev-server workflow for Musea.

Musea Component Gallery

Use Musea when you want Vue-native component examples, documentation, tokens, VRT, and a11y checks:

vp install -D @vizejs/vite-plugin @vizejs/vite-plugin-musea vize

// vite.config.ts
import { defineConfig } from "vite";
import vize from "@vizejs/vite-plugin";
import { musea } from "@vizejs/vite-plugin-musea";

export default defineConfig({
  plugins: [
    vize(),
    musea({
      include: ["src/**/*.art.vue"],
      basePath: "/__musea__",
      previewCss: ["src/styles/main.css"],
    }),
  ],
});

Run your Vite dev server and open /__musea__. See Musea for art files, preview setup, design tokens, VRT, and generated variants.

Oxlint Integration

Run Vize's Vue diagnostics inside Oxlint:

vp install -D oxlint oxlint-plugin-vize

{
  "plugins": ["vue"],
  "jsPlugins": ["oxlint-plugin-vize"],
  "rules": {
    "eqeqeq": "error",
    "vize/vue/require-v-for-key": "error",
    "vize/vue/no-v-html": "warn"
  },
  "settings": {
    "vize": {
      "preset": "general-recommended",
      "helpLevel": "short"
    }
  }
}

For terminal-first usage, prefer:

vp exec oxlint-vize -c .oxlintrc.json -f stylish src

Editor Support

For day-to-day Vue editing, keep using vuejs/language-tools for now. Vize editor features are designed for incremental opt-in.

VS Code starting point:

{
  "vize.enable": true,
  "vize.lint.enable": true,
  "vize.typecheck.enable": false,
  "vize.editor.enable": false,
  "vize.formatting.enable": false
}

Zed starting point:

{
  "languages": {
    "Vue": {
      "language_servers": ["vize", "..."]
    }
  },
  "lsp": {
    "vize": {
      "initialization_options": {
        "lint": true
      }
    }
  }
}

Local Development

This repository uses Nix + Vite+ (vp) for local development. In this workspace, vp will use pnpm automatically.

nix develop
vp install --frozen-lockfile
vp check
vp fmt
vp dev
vp build