Vite+

Use one defineConfig for Vite+, the Vize compiler, native linter, formatter, and library declarations. Type-check with the content mapper. Install @vizejs/vite-plugin and your preferred compatible vite-plus version in the project:

vp install -D @vizejs/vite-plugin

Keep the integration settings in vite.config.ts; no separate Vize config is required for these tasks. Migrate an existing project with literal import/plugin diffs, or follow Getting Started.

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

export default defineConfig({}).withVue({});

Important

The helper requires Vite+ 0.2.3 or later.

Vite+ is an optional peer dependency. Vize uses the project's installed version and its configuration types; it never downloads or replaces Vite+. Earlier versions can mistake a custom defineConfig for Vite+'s own and skip its generated tasks (upstream fix). Ordinary Vite projects can keep the usual plugin entry point.

Configuration

import { defineConfig } from "@vizejs/vite-plugin/vite-plus";
import { defineVizeLintConfig, flatConfigs } from "oxlint-plugin-vize";

export default defineConfig({
  server: { port: 3000 },
  lint: {
    rules: { "no-debugger": "error" },
    ignorePatterns: ["dist/**"],
  },
  fmt: { ignorePatterns: ["dist/**"] },
}).withVue({
  lint: defineVizeLintConfig(...flatConfigs.recommended, ...flatConfigs.ecosystem, {
    ignorePatterns: ["dist/**"],
    rules: { "no-console": "warn" },
  }),
  fmt: { singleQuote: true },
  entries: [
    {
      files: ["src/admin/**/*.vue"],
      linter: { rules: { "vue/no-v-html": "off" } },
    },
  ],
});

Keep the root object as an ordinary, Vue-free Vite+ config. .withVue() composes the Vue flat lint layer with that root configuration, so the root no-debugger policy remains active alongside flatConfigs.recommended, flatConfigs.ecosystem, and the Vue-specific no-console rule. Use compile, typeCheck, lint, and fmt. lint is the host Oxlint block; its settings.vize and vize/* rules also configure the native linter. Keep entries[].linter for file-scoped native overrides. The older compiler, typeChecker, linter, and formatter names remain compatibility aliases, but do not specify an alias together with its replacement. See Shared Vue configuration for paths and scoped entries.

Canonical vue settings take precedence over the corresponding task convenience options. Supplying vue.lint makes the host Oxlint block own the lint pass and disables the duplicate native lint task. Keep TypeScript strictness and template options in the existing TypeScript project:

{
  "compilerOptions": { "strict": true, "noEmit": true },
  "vueCompilerOptions": { "strictTemplates": true },
  "include": ["src/**/*"]
}

The typechecker runs once per task, including check when lint requests it. The helper removes its integration fields before passing the remaining config to Vite+. Other Vite+ options keep their upstream types, including future additions. Objects, promises, functions and async configuration functions are accepted, with Vite's environment forwarded to config functions.

Extend an existing configuration

Keep root Vite+ settings in defineConfig and pass Vue settings directly to the chained helper:

import { defineConfig } from "@vizejs/vite-plugin/vite-plus";

export default defineConfig({
  server: { port: 3000 },
}).withVue({
  compiler: { sourceMap: true },
  formatter: { singleQuote: true },
});

This preserves existing Vite+ options, plugins and hooks and injects the Vue compiler once. There is no custom config extends, and dedicated vize.config.* files and top-level vize: settings are retired. Standard TypeScript extends and references in tsconfig.json remain supported.

The standalone withVue helper and the withVize compatibility name remain supported, but new configuration should export the direct defineConfig({ ... }).withVue({ ... }) chain shown above.

Tasks

The recommended typecheck is the content mapper. TypeScript 7.1 runs tsc --runExternalCode --noEmit. tsrs is a drop-in of the same tsconfig: tsrs --runExternalCode --noEmit. vp run typecheck is the packaged checker, and vp run check includes it.

Pass paths after -- to check, lint, and format tasks. Formatting also accepts --check or --write. Put tool options in the corresponding config section. Checks continue after diagnostics so one failing tool does not hide the others. Generated tasks are uncached by default. Opt in to Vite+ caching for the read-only lint, fmt:check, check, and typecheck tasks:

import { defineConfig } from "@vizejs/vite-plugin/vite-plus";
export default defineConfig({}, { taskCache: true }).withVue({});

Vite+ automatically tracks source files, configuration imports, dependencies, and directory entries. Generated node_modules/.vize/** and **/.vize/** files are excluded from cache inputs, and checks never restore output files. Source-writing tasks such as fmt and lint:fix remain uncached. Passing --fix to a cached check still runs on changed inputs, including reintroducing the same unformatted source after a previous fix. Existing run.tasks keep their own cache policy, and renaming a generated task preserves its policy. Both the Vite+ 0.x and 1.x cache APIs are supported.

Warning

Custom tasks use vp run. Built-in vp check, vp lint, and vp fmt do not invoke these tasks.

Built-in vp build, vp dev, and vp pack already use the configured compiler or pack hooks.

Existing package scripts are preserved. A pre-existing check script causes the generated task to be named vize:check; the same rule applies to other names. Explicit run.tasks definitions take precedence. Rename or disable generated tasks with the optional integration argument:

import { defineConfig } from "@vizejs/vite-plugin/vite-plus";
export default defineConfig(
  { run: { tasks: { deploy: "your-deploy-command" } } },
  { tasks: { check: "verify", preview: false } },
).withVue({});

tasks: false disables all generated tasks.

Lint and formatter ownership

Vize's native linter runs alongside Oxlint, including Oxlint's JS/TS diagnostics inside Vue files. No oxlint-plugin-vize registration is needed. Overlapping Vue rules are disabled in Oxlint by default, using the installed tool's rule catalog. Explicit lint.rules and overrides can re-enable a rule.

Vize formats **/*.vue, which is excluded from Oxfmt by default. Other files stay with Oxfmt. Set lint.vue: false or fmt.vue: false to return the corresponding responsibility to Vite+. The integration option conflicts: false disables automatic overlap handling.

fmt.ignorePatterns applies to both formatters, so generated or vendored Vue files stay untouched. An entry that excludes every Vue file (**/*.vue or *.vue) only keeps .vue away from Oxfmt, as the integration does by default, so conflicts: false projects can add it themselves; vize fmt still formats them. To use lint.vue: false or fmt.vue: false, omit the corresponding shared native settings that would explicitly enable that tool. lint.vue.locale (en, ja, or zh) and helpLevel (full, short, or none) control native diagnostics without passing unsupported flags to Oxlint.

The compiler replaces an existing vite:vue plugin, including nested and async plugin lists, to avoid compiling a Vue file twice. Move native options to vue.compiler and plugin-only controls to compiler. To retain the original compiler, omit vue.compiler and use compiler: false.

Library declarations and maps

import { defineConfig } from "@vizejs/vite-plugin/vite-plus";
export default defineConfig({
  pack: {
    entry: ["src/index.ts"],
    outDir: "dist",
    format: ["esm"],
    vue: {
      dts: true,
      declarationMap: true,
      sourcemap: true,
    },
  },
}).withVue({});

Vue library bundling uses Vize's Rolldown integration. Providing pack.vue enables native declaration generation by default; dts: false opts out. Declarations are emitted after a successful bundle, and type errors fail the pack command. Native declaration generation replaces tsdown's declaration pass for that pack entry, so it understands Vue SFCs.

declarationDir overrides the output directory, otherwise pack.outDir is used. tsconfig selects a TypeScript project. declarationMap overrides that project's map setting without modifying authored tsconfig files. sourcemap controls compiler and bundle maps. Each entry in a pack array can configure vue independently; pack.vue: false leaves that entry with Vite+.

Editor setup

Run vp run editor:setup to add the Vize and Vite Plus extension recommendations and Vue-specific editor defaults. It preserves comments, existing recommendations, explicit settings, and the formatter chosen for other languages.

See Vite+ editor setup for the recommended responsibilities and how to share native configuration with the editor.