--- url: https://toolchain.dbx.studio/guide/vite.md --- # Vite+ There are two ways to use dbx with Vite: * **Plugin mode (recommended):** put the toolchain config inline in the `dbx()` Vite plugin inside `vite.config.*`. No `dbx.config.*` is required, and dbx never manages `vite.config.*` because the plugin lives there. * **Config mode:** keep the whole Vite+ config in `dbx.config.*` under `toolchain.vite`, and let `dbx sync` write a thin `vite.config.ts` shim. Both can be combined: a `dbx.config.*` provides shared config and the plugin options are merged on top. ## Vite+ as the local CLI Install `vite-plus` as a dev dependency and let it provide Vite, Vitest, Oxfmt, Oxlint, Rolldown and tsdown. Do not add those packages separately. On Yarn, add `resolutions` so every dependency resolves the copies Vite+ bundles: ```json [package.json] { "resolutions": { "vite": "npm:@voidzero-dev/vite-plus-core@", "vitest": "" } } ``` Run `vp toolchain vite-plus-core` and `vp toolchain vitest` to get the exact versions. Without the Vitest pin, a dependency or workspace package can pull a different Vitest and split its internals (mocks, `expect`, runner state). Use `vp` in the package scripts (`vp dev`, `vp build`, `vp test`, `vp check`, `vp pack`) so contributors only need the project-local CLI; a global `vp` delegates to the same installed version. ## Plugin mode ```ts [vite.config.ts] import { defineConfig } from 'vite-plus'; // or 'vite' for plain Vite import { dbx } from '@deltabox/toolchain/vite'; export default defineConfig({ plugins: [ dbx({ toolchain: { project: { name: 'my-app', scope: '@org' }, fmt: { oxc: true }, lint: { oxc: true }, ci: { sync: true }, changelog: { preset: 'conventional' }, }, }), ], // your usual Vite config }); ``` The plugin carries the config inline and the dbx CLI (sync, projects, watch and the VS Code extension) reads it back from `vite.config.*`. The plugin also derives the Vite options from the dbx sections: | dbx section | Vite option | | ----------- | -------------------------------------- | | `logger` | `logLevel` / `customLogger` | | `watch` | `server.watch` (the `exclude` globs) | | `fmt` | Vite+ `fmt` (only on a Vite+ project) | | `lint` | Vite+ `lint` (only on a Vite+ project) | The `vite` section is deliberately omitted from the plugin options: the Vite config is the user config in plugin mode. Vite+ keys are only added when the project declares `vite-plus`; a pure Vite project gets only standard Vite options. Vite+ CLI passthroughs (`dbx vite:*`) are refused unless Vite+ is installed/detected. `dbx sync` runs before the dev server/build (or `dbx sync --check` in CI) and re-syncs when `vite.config.*`, `dbx.config.*` or a tsconfig input changes. Builtin scaffolds (`dbx create`, `dbx project:init`, `dbx project:init:workspace`) use plugin mode: they generate a `vite.config.*` with `dbx({ toolchain })`, Vitest (`test`) and Vite+ tasks (`run.tasks`) instead of a `dbx.config.*`. The scaffolded packages depend on `vite-plus` and use `vp` for build/test, so no separate `vitest` or `tsdown` dependency is written. ## Config mode The `vite` section holds the **entire Vite+ configuration**. Every key is passed through verbatim to Vite+, so `dbx.config.*` stays the only hand-authored root config; `dbx sync` writes a thin root `vite.config.ts` that resolves it at load time. ```ts [dbx.config.ts] export default defineConfig({ toolchain: { vite: { fmt: { semi: true, singleQuote: true }, lint: { ignorePatterns: ['dist/**'] }, test: { include: ['src/**/*.test.ts'], environment: 'node' }, run: { tasks: { build: { command: 'vp pack' } } }, }, }, }); ``` The section is typed as Vite+'s own config (`ToolchainViteConfig` = Vite's `UserConfig` as augmented by Vite+), so the whole Vite+ surface autocompletes in `dbx.config.ts`. ## The generated shim `dbx sync` writes a fixed `vite.config.ts`: ```ts [vite.config.ts] // Generated by @deltabox/toolchain. import { defineConfig, type ViteUserConfig } from 'vite-plus'; import { resolveVite } from '@deltabox/toolchain/vite'; export default defineConfig(resolveVite({ cwd: import.meta.dirname })); ``` The shim imports `defineConfig` from whichever Vite package the project installs — `vite` or `vite-plus` (detected from `package.json`, walking up so a hoisted workspace dependency is found). For a plain `vite` project it imports `defineConfig, type UserConfig` from `vite` and calls `resolveVite`, so the same shim type-checks against both. `resolveVite(options?)` resolves the **same-directory** `dbx.config.*` (so a nested workspace `vite.config.ts` uses its own config), or the `toolchain` you pass, then returns `toolchain.vite`. You can also pass inline overrides with `resolveVite({ vite: { ... } })`, which are deep-merged over the loaded section. The file never drifts, because the real config stays in `dbx.config.*`. The root shim must live at the **root**: `vp run`, `vp check` and `vp staged` do not accept `--config`, so the shim has to be the file Vite+ loads. ## Options | Option | Type | Default | Description | | -------- | ------------------- | ------- | ----------------------------------------------- | | `config` | `boolean \| string` | `true` | Write the managed shim; a string sets its path. | Everything else under `vite` is Vite+ config (plugins, `test`, `lint`, `fmt`, `run.tasks`, ...). `vite.fmt` / `vite.lint` override `toolchain.fmt.oxc` / `toolchain.lint.oxc` (deep merge). `fmt: true` / `lint: true` use the shared `DEFAULT_FMT_RULES` / `DEFAULT_LINT_RULES`; an options object is merged over them. Their ignore lists are exported as `DEFAULT_FMT_IGNORE_PATTERNS` / `DEFAULT_LINT_IGNORE_PATTERNS` (both layered over `DEFAULT_IGNORE_PATTERNS`) from `@deltabox/toolchain` and `@deltabox/toolchain/shared`, so you can extend them instead of repeating the defaults. Import sorting is part of those defaults: `sortImports` gets a `workspace` custom group resolved from every dbx project (see `resolveFmtCustomGroups`), so workspace packages do not need manual groups. Set `vite: { config: false }` to leave a hand-written `vite.config.ts` alone (the section is still read for provider colouring and the `dbx` provider passthrough). `config: 'config/vite.custom.ts'` writes the shim there instead (relative to the project, or an absolute path inside it). ## Nested workspaces `vite` is **never inherited**. A workspace with no `vite` section keeps its hand-written `vite.config.*` untouched; `dbx sync` only writes a shim when the project declares `vite` itself. Declare the settings the workspace needs in its own config: ```ts [packages/web/dbx.config.ts] export default defineConfig({ toolchain: { vite: { shim: 'static', resolve: { tsconfigPaths: true }, run: { tasks: { build: { command: 'vp pack' } } }, }, }, }); ``` `vite.fmt` / `vite.lint` are the exception: when the workspace opts into `fmt` / `lint`, they are hoisted into the top-level `fmt.oxc` / `lint.oxc` before inheritance, so shared formatting still flows down. Vite+ recommends one root `fmt` / `lint` block with `overrides` for per-package rules; per-workspace formatter/linter blocks are not applied by `vp check`, so prefer the root `fmt.oxc.overrides` / `lint.oxc.overrides` (see the [Monorepo guide](/guide/monorepo#shared-formatting-and-linting)). ## Keep the shim out of Oxfmt Add the shim to `vite.fmt.ignorePatterns`, otherwise `vp fmt` rewrites the generated file and `dbx sync --check` reports drift: ```ts vite: { fmt: { ignorePatterns: ['/vite.config.ts']; } } ``` In a monorepo, put `**/vite.config.ts` on the **root** top-level `fmt.oxc` config so every workspace shim is covered (an `ignorePatterns` array in a workspace replaces the root's list). `dbx migrate --from vite` adds the ignore for you (see [Migrations](/guide/migrations/#vite-config)). When `fmt` / `lint` are defined, `dbx sync` also writes `.oxfmtrc.json` / `.oxlintrc.json` for the Oxc VS Code extension. They are root-only unless a workspace config defines its own `fmt` / `lint`. ## Commands Vite+ commands are reachable directly or through the `vite` namespace, and are registered as a provider (see [Providers](/guide/providers)): ```sh dbx fmt # the active formatter (vp fmt when Oxc) dbx run -r build # forwards to `vp run -r build` dbx vite dev # explicit namespace (always works) dbx vite:build # named alias for `vp build` ``` A bare `dbx ` is forwarded to Vite+ when the name (or a Vite+ alias) matches — built-in commands win, so `dbx migrate` stays the toolchain's migration. `dbx fmt` / `dbx lint` route to the configured/discovered Biome/Prettier/Dprint/ESLint tool, and keep the `vp` passthrough when the active tool is Oxc (see [Formatting & linting](/guide/formatting#running-the-active-tool)). ## Programmatic API ```ts import { resolveVite, renderViteConfig, viteConfigObject, viteProvider, viteSyncTask, } from '@deltabox/toolchain/vite'; ``` | Export | Description | | ------------------------------ | --------------------------------------------------------------------------------- | | `resolveVite(options?)` | Resolve `toolchain.vite` (or a passed `toolchain`), with inline `vite` overrides. | | `detectViteSpecifier(cwd)` | Which package (`vite` / `vite-plus`) the project has, for the shim import. | | `renderViteConfig(specifier?)` | The managed `vite.config.ts` shim source (defaults to `vite-plus`). | | `viteConfigObject(config?)` | The `vite` section without the toolchain opt-out `config`. | | `viteSyncTask()` | The sync task (writes the shim). | | `viteProvider()` | The Vite+ provider descriptor. | See [Configuration](/guide/config/vite) for the `dbx.config` integration and the [Providers](/guide/providers) guide for the passthrough commands.