Jest Still Works, But There’s a Problem
If you’re using Jest with TypeScript, you’ve probably seen this scenario: running the test suite for the first time takes 10–15 seconds just to start up, then every time you edit a small file you wait a few more seconds. The reason is that Jest needs to transpile TypeScript through Babel or ts-jest before running, while its module system still operates in the old CommonJS style.
Vitest addresses exactly that. TypeScript is processed by esbuild — many times faster than Babel. More importantly, the entire transform pipeline only starts once, without resetting every time you edit a file.
I tried migrating a recently completed web app project — around 180 test files, 5 developers working together — from Jest to Vitest. Full test suite runtime dropped from 47 seconds down to 11 seconds. Watch mode is nearly instantaneous. The whole team noticed the difference after the first day.
Installing Vitest in a TypeScript Project
Projects already using Vite have an easier time, but it’s not required — Vitest runs standalone just fine. Installation is like any other dev dependency:
Adding Vitest to Your Project
# If using npm
npm install -D vitest
# If using pnpm
pnpm add -D vitest
# If using yarn
yarn add -D vitest
Testing UI components (React, Vue…) requires the jsdom environment:
npm install -D @vitest/ui jsdom
Adding Scripts to package.json
{
"scripts": {
"test": "vitest",
"test:run": "vitest run",
"test:ui": "vitest --ui",
"coverage": "vitest run --coverage"
}
}
vitest without run runs in watch mode — it auto-detects file changes and re-runs related tests. vitest run runs once then exits, used for CI/CD.
Detailed Configuration
Integrating into vite.config.ts
Already have a vite.config.ts? Add the test block directly — no need for a separate config file:
/// <reference types="vitest" />
import { defineConfig } from 'vite'
export default defineConfig({
test: {
globals: true, // use describe/it/expect without importing
environment: 'jsdom', // remove this line for pure Node.js tests
setupFiles: './src/test/setup.ts',
include: ['**/*.{test,spec}.{ts,tsx}'],
coverage: {
reporter: ['text', 'html'],
exclude: ['node_modules/', 'src/test/']
}
}
})
The /// <reference types="vitest" /> line at the top tells TypeScript to recognize types for describe, it, expect… without any extra declarations.
Or Use a Separate vitest.config.ts File
Not using Vite? Create a standalone vitest.config.ts file:
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
globals: true,
environment: 'node',
include: ['src/**/*.test.ts'],
reporters: ['verbose']
}
})
Updating tsconfig.json
Add Vitest types to tsconfig.json so the IDE doesn’t report errors:
{
"compilerOptions": {
"types": ["vitest/globals"]
}
}
Writing Tests — Syntax Nearly 100% Identical to Jest
This is why migrating to Vitest is less painful than you’d expect: old Jest test files run immediately without any changes. If you already know Jest, there’s nothing new to learn.
// src/utils/format.test.ts
import { describe, it, expect } from 'vitest'
import { formatCurrency } from './format'
describe('formatCurrency', () => {
it('formats VND amount correctly', () => {
expect(formatCurrency(1500000)).toBe('1,500,000 ₫')
})
it('returns 0 ₫ when input is 0', () => {
expect(formatCurrency(0)).toBe('0 ₫')
})
it('handles negative numbers', () => {
expect(formatCurrency(-50000)).toBe('-50,000 ₫')
})
})
Enable globals: true in config to drop the import line entirely — use it just like Jest.
In-source Testing — A Unique Feature Exclusive to Vitest
Jest doesn’t have this. In-source Testing lets you write tests directly inside the source file, without creating a separate .test.ts file. Small utility function? The test sits right below the function definition — anyone reading the code immediately sees what the function does without opening another file.
How It Works
Vitest uses an if (import.meta.vitest) block. In production builds, Vite tree-shakes the entire block out — bundle size is unaffected:
// src/utils/math.ts
export function clamp(value: number, min: number, max: number): number {
return Math.min(Math.max(value, min), max)
}
// Test lives directly in the source file
if (import.meta.vitest) {
const { it, expect } = import.meta.vitest
it('clamp keeps value within [min, max] range', () => {
expect(clamp(5, 0, 10)).toBe(5)
expect(clamp(-1, 0, 10)).toBe(0)
expect(clamp(15, 0, 10)).toBe(10)
})
}
Enabling In-source Testing in Config
// vite.config.ts
export default defineConfig({
test: {
includeSource: ['src/**/*.ts'] // add this line
},
define: {
// Remove test code from production build
'import.meta.vitest': 'undefined'
}
})
I use this pattern for helper functions in projects: instead of creating a separate date-utils.test.ts file, tests live right below the function definition. During code review, readers immediately see what the function does and what results to expect — no need to open another file.
Running Tests and Tracking Coverage
Running Tests for the First Time
# Watch mode (development)
npm test
# Run once (CI)
npm run test:run
# View visual UI in browser
npm run test:ui
UI mode (--ui) opens a dashboard in the browser, displaying each test in a file tree with clear pass/fail color coding. Useful when debugging a large test suite with many nested describes.
Viewing the Coverage Report
Install the coverage package:
npm install -D @vitest/coverage-v8
npm run coverage
The output shows a stats table per file: what percentage of statements, branches, functions, and lines are covered. An HTML report is generated in the coverage/ directory — open it in a browser to see line-by-line details.
Integrating with CI/CD
In GitHub Actions or GitLab CI, replace jest with vitest run:
- name: Run tests
run: npm run test:run
- name: Check coverage
run: npm run coverage
Key Differences to Note When Migrating from Jest
- Mock module: use
vi.mock()instead ofjest.mock() - Spy:
vi.spyOn()instead ofjest.spyOn() - Fake timers:
vi.useFakeTimers()instead ofjest.useFakeTimers() - Snapshot: syntax stays the same, snapshot files stored in
__snapshots__as before
Most of the time you just need to find-and-replace jest. with vi. and you’re done. I migrated 180 test files with a sed command in 2 minutes — only a few spots needed manual fixes due to more complex logic.
When to Use Vitest vs. When to Keep Jest
The decision isn’t complicated. Using Vite? Choose Vitest, no further thought needed. Building a standalone TypeScript library? Vitest is a solid default choice there too.
Old CRA, Next.js with Webpack, or a specialized setup you don’t want to touch — Jest remains stable, no need to switch.
Starting a new project or migrating to Vite? Pick Vitest from the start. 11 seconds instead of 47 seconds per full test suite run — that adds up to significant time saved over a few months of development.

