Compile error in vitest typescript project

[NicoleRauch]

• @testing-library/jest-dom version: 6.6.3
• node version: 22.4.1
• jest (or vitest) version: vitest 4.1.6
• npm (or yarn) version: npm 10.8.1

Relevant code or config:

tsconfig.json

    "types": ["node", "vitest/globals", "@testing-library/jest-dom"]

What you did:

When running tsc --noemit

What happened:

Reproduction:

Create a file with just the line

import "@testing-library/jest-dom";

and compile it with npx tsc --noemit [filename].

Problem description:

jest-dom references jest types in the type definitions, but I am not using jest, so I don't have these types.
Adding them gives different errors because they conflict with the vitest types.

Suggested solution:

When I remove the line in question from jest.d.ts, it compiles.

[FrancoKaddour]

Confirmed the root cause in the type entrypoints. The default entry (. → types/index.d.ts) does /// <reference path="jest.d.ts" />, and types/jest.d.ts opens with /// <reference types="jest" />. So resolving the default types eagerly pulls in @types/jest — which a vitest-only project doesn't have, hence the compile error.

There are really two things tangled here:

1. Usage (the immediate fix). For a vitest project the types to load are @testing-library/jest-dom/vitest, not the bare package — the ./vitest entry uses declare module 'vitest' and has no jest reference. Putting @testing-library/jest-dom in tsconfig types: [...] pulls the jest entry. This is exactly what the open docs PR #718 proposes to clarify, and it would resolve the reported setup.

2. Design (why it's sharp). Even with correct usage, the default entry hard-erroring when @types/jest is absent is fragile — the /// <reference types="jest" /> couples the default entry to jest being installed. Simply deleting that line (the suggested fix) isn't safe though: jest users who rely on the bare import '@testing-library/jest-dom' to auto-load jest globals would then get TS2304: Cannot find name 'expect'. So it's a change to the published type contract.

A couple of directions, depending on what you'd prefer:

• Keep the reference but land the docs: Use the according types with vitest #718 docs fix so vitest users are pointed at /vitest (lowest risk).
• Or decouple the default entry from an ambient @types/jest dependency (e.g. import type from @jest/globals inside jest.d.ts instead of the triple-slash reference types="jest"), so it doesn't hard-fail when jest types aren't present.

Happy to put up a PR for whichever direction — which would you rather take?

[burtek]

Doesn't @testing-library/jest-dom/vitest exist for this very reason? For vitest projects just replace import of @testing-library/jest-dom with @testing-library/jest-dom/vitest. See https://github.com/testing-library/jest-dom#with-vitest

Unless I'm not getting what this is about.

Also NB: This won't work with the newest vitest 5.0, see #738

[FrancoKaddour]

Right, @testing-library/jest-dom/vitest is the correct import for vitest projects — that's point 1 above, and it does resolve the reported setup. 👍

The reason I flagged a second angle is that the default entry still hard-errors when @types/jest isn't installed (via the /// <reference types="jest" /> in jest.d.ts), so a bare import '@testing-library/jest-dom' fails to typecheck in a vitest-only project even though nothing about that import is jest-specific at runtime. Whether that's worth decoupling (vs. just documenting /vitest harder, per #718) is the maintainer call I was asking about.

Good catch on #738 though — that's a separate one (vitest 5's Assertion shape breaking the /vitest augmentation), orthogonal to this reference issue. Worth keeping them apart so neither fix masks the other.