Vitest 02 🧪 Installation — npm install -D vitest & Node/Vite Requirements
Vitest installs with a single command and inherits Vite’s configuration, but it has hard version floors for both Vite and Node.js that determine whether the install will work at all. The current documentation states that Vitest requires Vite >=v6.4.0 and Node >=v22.12.0 . These are not suggestions; a project on an older Vite or Node version will hit errors that look like configuration problems but are actually version mismatches.
This chapter covers the installation command, the version requirements, the optional dependencies that are installed separately, and the configuration check that confirms the setup is correct. The sections that follow walk through the install, the version floors, and the companion packages that most projects add.
Key point: npm install -D vitest is the entire installation for a Vite project; Vitest requires Vite >=v6.4.0 and Node >=v22.12.0, and the test block in vite.config.ts is where the configuration lives—no separate vitest.config.ts is needed unless the project has no Vite config.
a. The install command and version floors
Vitest is installed as a development dependency. The package manager variants are the standard ones: npm install -D vitest, yarn add -D vitest, pnpm add -D vitest, and bun add -D vitest . The npx vitest command works without a local install, but the documentation recommends a local copy in package.json so the version is pinned and reproducible .
The version requirements are documented as a warning box on the getting-started page. The current Vitest release (v5) requires Vite v6.4.0 or newer and Node v22.12.0 or newer . A project that was scaffolded with an older Vite version needs to upgrade Vite first; a project on an older Node LTS needs to upgrade Node. The older Vitest v3 documentation lists lower floors (Vite >=v5.0.0, Node >=v18.0.0), which is why a project that followed an old tutorial may find the current Vitest does not install cleanly .
# Check current versions before installing
node --version # must be >= v22.12.0
npm ls vite # must be >= v6.4.0
# Install Vitest
npm install -D vitest
The .vitest directory is where Vitest and its integrations store generated artifacts. The documentation recommends adding it to .gitignore . This is a small thing that prevents generated files from appearing in commits.
b. The shared configuration
Vitest reads vite.config.ts and uses the same resolve.alias, plugins, and define settings that the application uses. The test-specific configuration lives in a test block inside that same file, not in a separate vitest.config.ts . A separate config file is only necessary when the project does not have a Vite config at all, or when the test configuration must diverge significantly from the build configuration.
// vite.config.ts
import { defineConfig } from "vite";
export default defineConfig({
resolve: {
alias: { "@": "/src" }, // shared by app and tests
},
test: {
environment: "jsdom", // or "happy-dom" or "node"
setupFiles: ["./test/setup.ts"],
globals: true, // optional: mimic Jest globals
},
});
The environment setting determines the DOM implementation. jsdom is the default choice for component tests; happy-dom is a lighter alternative; node is for tests that do not need a DOM . The setupFiles array lists files that run before each test file, which is where testing-library cleanup and custom matchers are registered. The globals setting is off by default in Vitest, unlike Jest; enabling it makes describe, it, and expect available without imports, but the explicit import from vitest is the recommended pattern for type safety .
c. Companion packages
Vitest core does not include the DOM environment, the testing-library utilities, or the UI. Those are installed separately when the project needs them.
For component testing, the common additions are jsdom (or happy-dom) and @testing-library/react (or the equivalent for the framework). The @testing-library/jest-dom matchers are also added separately; Vitest does not bundle them . For the browser UI, @vitest/ui is installed and run with vitest --ui; the UI now requires token authentication, and the URL printed by the command includes the token .
# Component testing
npm install -D jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom
# Optional: browser UI
npm install -D @vitest/ui
The companion packages are not required for a project that only runs unit tests on pure functions. A Node-only test suite needs nothing beyond vitest itself. The additions are for DOM rendering, custom matchers, and the interactive UI.
Complete Example Session
// ============================================
// PART 1: VERSION CHECK
// ============================================
// node --version
// v22.12.0 or newer
//
// npm ls vite
// vite@6.4.0 or newer
// ============================================
// PART 2: INSTALL
// ============================================
// npm install -D vitest
// ============================================
// PART 3: THE SHARED CONFIG
// ============================================
// vite.config.ts
import { defineConfig } from "vite";
export default defineConfig({
test: {
environment: "node", // unit tests, no DOM
globals: false, // explicit imports
},
});
// ============================================
// PART 4: A FIRST TEST
// ============================================
// src/math.test.ts
import { describe, it, expect } from "vitest";
import { add } from "./math";
describe("add", () => {
it("adds two numbers", () => {
expect(add(1, 2)).toBe(3);
});
});
// ============================================
// PART 5: RUN
// ============================================
// npx vitest run (single run, CI)
// npx vitest (watch mode, development)
// ============================================
// PART 6: GITIGNORE
// ============================================
// .vitest/
The parts covered the version check, the install, the shared config, a first test, the run commands, and the gitignore entry.
Quick Reference
Installation
| Command | Effect |
|---|---|
npm install -D vitest | Adds Vitest to devDependencies |
npx vitest | Runs without local install |
npx vitest run | Single run (CI) |
npx vitest | Watch mode |
Version Requirements
| Requirement | Minimum |
|---|---|
| Vite | >= v6.4.0 |
| Node.js | >= v22.12.0 |
Optional Packages
| Package | Purpose |
|---|---|
jsdom | DOM environment |
happy-dom | Lighter DOM alternative |
@testing-library/react | Component rendering |
@testing-library/jest-dom | DOM matchers |
@vitest/ui | Browser UI |
Configuration Location
| File | When |
|---|---|
vite.config.ts | Default; shares resolve/plugins |
vitest.config.ts | No Vite config, or divergent test setup |
Best Practices
✅ Do This:
# Check versions before installing
node --version && npm ls vite # ✅
# Install as dev dependency
npm install -D vitest # ✅
# Add .vitest to .gitignore
echo ".vitest/" >> .gitignore # ✅
// Configure in vite.config.ts
export default defineConfig({ test: { environment: "node" } }); // ✅
❌ Don’t Do This:
# Install without checking Node/Vite versions
npm install -D vitest # may fail on old Node # ❌
# Install as production dependency
npm install vitest # ❌
# Commit .vitest artifacts
git add .vitest/ # ❌
Common Pitfalls
| Pitfall | Why It Happens | Fix |
|---|---|---|
| Install fails on old Node | Node < v22.12.0 | Upgrade Node |
| Install fails on old Vite | Vite < v6.4.0 | Upgrade Vite |
| Globals undefined | globals: false default | Import from vitest or enable globals |
| testing-library cleanup not running | Globals disabled | Enable globals or import cleanup |
| Separate config not read | vitest.config.ts not picked up | Use vite.config.ts test block |
Real-World Examples
1. Install
npm install -D vitest
2. Version check
node --version && npm ls vite
3. Shared config
export default defineConfig({ test: { environment: "node" } });
4. Component test setup
npm install -D jsdom @testing-library/react @testing-library/jest-dom
5. Run in CI
npx vitest run
6. Watch mode
npx vitest
7. Gitignore
echo ".vitest/" >> .gitignore
8. Optional UI
npm install -D @vitest/ui && npx vitest --ui
9. Explicit imports
import { describe, it, expect } from "vitest";
10. Globals enabled
test: { globals: true }
Visual
Install Flow
┌─────────────────────────────────────────────────────────┐
│ CHECK VERSIONS │
│ node >= v22.12.0 │
│ vite >= v6.4.0 │
│ │ │
│ ┌────┴────┐ │
│ ▼ ▼ │
│ OK FAIL │
│ │ │ │
│ ▼ ▼ │
│ npm i -D Upgrade │
│ vitest Node/Vite │
│ │ │
│ ▼ │
│ Add test block to vite.config.ts │
└─────────────────────────────────────────────────────────┘
Version Floors
┌─────────────────────────────────────────────────────────┐
│ VITEST v5 REQUIREMENTS │
│ │
│ Vite: >= v6.4.0 │
│ Node: >= v22.12.0 │
│ │
│ OLDER (v3 docs): │
│ Vite: >= v5.0.0 │
│ Node: >= v18.0.0 │
│ │
│ Following an old tutorial may install the wrong │
│ version for your project. │
└─────────────────────────────────────────────────────────┘
Config Location
┌─────────────────────────────────────────────────────────┐
│ vite.config.ts │
│ ┌──────────────────────────────────────────┐ │
│ │ resolve.alias, plugins (shared) │ │
│ │ test: { environment, setupFiles } │ │
│ └──────────────────────────────────────────┘ │
│ │ │
│ ┌────┴────┐ │
│ ▼ ▼ │
│ App/Build Tests │
│ │
│ One file, one resolution pipeline │
└─────────────────────────────────────────────────────────┘
Summary
| Item | Value |
|---|---|
| Install | npm install -D vitest |
| Vite requirement | >= v6.4.0 |
| Node requirement | >= v22.12.0 |
| Config location | vite.config.ts test block |
| Globals default | Off |
| Optional DOM | jsdom or happy-dom |
| Gitignore | .vitest/ |
Key takeaways:
- The install is one command, but the version floors are hard. Vitest v5 requires Vite v6.4.0+ and Node v22.12.0+. A project on older versions needs to upgrade before the install will work .
- The configuration lives in
vite.config.ts. Thetestblock is Vitest-specific, but theresolve.aliasandpluginsare shared with the app. A separatevitest.config.tsis only needed when there is no Vite config or the test setup diverges . - Globals are off by default. Unlike Jest, Vitest does not inject
describe,it, andexpect. Import them fromvitest, or enableglobals: trueto mimic Jest—but note that testing-library cleanup does not run automatically without globals . - The companion packages are installed separately.
jsdom, testing-library, and@vitest/uiare not bundled. A Node-only unit test suite needs none of them; a component test suite needs the DOM and the testing-library packages .
Remember: The installation is the easy part; the version check is the part that fails silently. Run node --version and npm ls vite before installing, add the test block to the existing Vite config, and keep globals off unless the project is migrating from Jest and needs the compatibility. The .vitest directory is generated; keep it out of git.
Stop using slow, ad-bloated tool sites! 🤮
🔎 Search “KandZ Tools” on Google to use many professional utilities for free.
KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)
⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free
🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!