Vite+
There are two ways to use dbx with Vite:
- Plugin mode (recommended): put the toolchain config inline in the
dbx()Vite plugin insidevite.config.*. Nodbx.config.*is required, and dbx never managesvite.config.*because the plugin lives there. - Config mode: keep the whole Vite+ config in
dbx.config.*undertoolchain.vite, and letdbx syncwrite a thinvite.config.tsshim.
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:
{
"resolutions": {
"vite": "npm:@voidzero-dev/vite-plus-core@<core-version>",
"vitest": "<vitest-version>"
}
}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
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.
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:
// Generated by @deltabox/toolchain.
import { defineConfig, type ViteUserConfig } from 'vite-plus';
import { resolveVite } from '@deltabox/toolchain/vite';
export default defineConfig(resolveVite<ViteUserConfig>({ 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<UserConfig>, 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:
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).
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:
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).
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):
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 <command> 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).
Programmatic API
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 for the dbx.config integration and the Providers guide for the passthrough commands.