How to set up Vitest with Next.js
Vitest and React Testing Library are frequently used together for Unit Testing. This guide will show you how to set up Vitest with Next.js and write your first tests.
Good to know: Since
asyncServer Components are new to the React ecosystem, Vitest currently does not support them. While you can still run unit tests for synchronous Server and Client Components, we recommend using E2E tests forasynccomponents.
Quickstart
You can use create-next-app with the Next.js with-vitest example to quickly get started:
pnpm create next-app --example with-vitest with-vitest-appnpx create-next-app@latest --example with-vitest with-vitest-appyarn create next-app --example with-vitest with-vitest-appbun create next-app --example with-vitest with-vitest-appManual Setup
Vitest 5 and jsdom 31 require a newer Node.js version than the Next.js minimum. Use Node.js 24.15 or later in the Node.js 24 release line for the setup below. If you use another Node.js version, choose compatible dependency versions using the Vitest installation requirements and jsdom requirements.
For TypeScript projects, the commands below also install @types/node@24 to match this runtime and satisfy Vitest 5's peer dependency. This replaces the @types/node@20 dependency in projects generated by create-next-app. Upgrading Node.js alone does not update these type definitions.
To manually set up Vitest, install vitest and the following packages as dev dependencies:
# Using TypeScript
pnpm add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom vite-tsconfig-paths @types/node@24
# Using JavaScript
pnpm add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom# Using TypeScript
npm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom vite-tsconfig-paths @types/node@24
# Using JavaScript
npm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom# Using TypeScript
yarn add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom vite-tsconfig-paths @types/node@24
# Using JavaScript
yarn add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom# Using TypeScript
bun add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom vite-tsconfig-paths @types/node@24
# Using JavaScript
bun add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/domCreate a vitest.config.mts|js file in the root of your project, and add the following options:
import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
import tsconfigPaths from 'vite-tsconfig-paths'
export default defineConfig({
plugins: [tsconfigPaths(), react()],
test: {
environment: 'jsdom',
},
})import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
export default defineConfig({
plugins: [react()],
test: {
environment: 'jsdom',
},
})For more information on configuring Vitest, please refer to the Vitest Configuration docs.
Then, add a test script to your package.json:
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"test": "vitest"
}
}When you run npm run test, Vitest will watch for changes in your project by default.
Creating your first Vitest Unit Test
Check that everything is working by creating a test to check if the <Page /> component successfully renders a heading:
import Link from 'next/link'
export default function Page() {
return (
<div>
<h1>Home</h1>
<Link href="/about">About</Link>
</div>
)
}import Link from 'next/link'
export default function Page() {
return (
<div>
<h1>Home</h1>
<Link href="/about">About</Link>
</div>
)
}import { expect, test } from 'vitest'
import { render, screen } from '@testing-library/react'
import Page from '../pages/index'
test('Page', () => {
render(<Page />)
expect(screen.getByRole('heading', { level: 1, name: 'Home' })).toBeDefined()
})import { expect, test } from 'vitest'
import { render, screen } from '@testing-library/react'
import Page from '../pages/index'
test('Page', () => {
render(<Page />)
expect(screen.getByRole('heading', { level: 1, name: 'Home' })).toBeDefined()
})Running your tests
Then, run the following command to run your tests:
pnpm testnpm run testyarn testbun run testAdditional Resources
You may find these resources helpful: