The Challenge of Testing Multiple Packages Together
A monorepo managed by tools like npm/yarn/pnpm workspaces or Turborepo typically contains many independent packages, each with its own package.json, source directory, and possibly its own test conventions, and running jest from the repository root needs to discover and correctly resolve test files and imports across all of them without accidentally picking up build output in a dist or node_modules folder. Left unconfigured, Jest's default rootDir and testPathIgnorePatterns can either miss tests nested deep inside packages/*/src or waste time re-running compiled duplicates of the same test found in a package's build output.
Cricket analogy: Similar to a domestic tournament like the Ranji Trophy needing one central scheduling system to correctly track matches across many regional teams without mixing up practice games with real fixtures, a monorepo's root Jest config must discover real test files across packages without mixing in stale build output.
Workspace-Aware Test Discovery with rootDir and testMatch
Running jest from the monorepo root generally needs a rootDir pointing at the repo root combined with a testMatch or testPathIgnorePatterns that excludes each package's dist, build, or .next output directories, alongside excluding the top-level node_modules while still allowing tests located inside individual packages' own source folders. Many teams instead prefer per-package Jest configs invoked via a task runner like Turborepo's turbo run test or Nx's nx run-many, letting each package's test command run independently and in parallel, with the monorepo tool handling dependency-aware ordering and caching rather than Jest itself trying to understand workspace boundaries.
Cricket analogy: Similar to a tournament organizer deciding whether to run one central schedule for all regional matches or let each regional board schedule its own fixtures independently, teams choose between one root Jest config or per-package configs run via a task runner like Turborepo.
// turbo.json (excerpt)
{
"pipeline": {
"test": {
"dependsOn": ["^build"],
"outputs": ["coverage/**"],
"cache": true
}
}
}
// runs each package's own "test" script (e.g. "jest") in parallel,
// respecting dependency order and Turborepo's remote cache
// $ turbo run testSharing Config with preset and moduleNameMapper
To avoid every package repeating the same transform, testEnvironment, and coverage thresholds, monorepos commonly publish an internal shared package, such as @myorg/jest-preset, that each package's jest.config.js references via the preset field, keeping only package-specific overrides local. Cross-package imports, like importing @myorg/ui from an app package before it's been built, are typically resolved in tests via moduleNameMapper pointing at each sibling package's src directory instead of its unbuilt or stale dist output, so a change in a shared package is immediately visible to a dependent package's tests without a rebuild step in between.
Cricket analogy: Similar to a national board publishing one official coaching manual that every regional academy references rather than each writing its own from scratch, a shared @myorg/jest-preset package lets every monorepo package reference common Jest settings via the preset field.
Mapping a workspace package's import to its src directory via moduleNameMapper, e.g. '^@myorg/ui$': '<rootDir>/../../packages/ui/src/index.ts', means tests see the latest TypeScript source directly, but this typically requires ts-jest or a Babel transform capable of compiling that sibling package's source on the fly, since Jest itself doesn't transpile TypeScript without a transform configured.
Caching and CI Performance at Scale
As a monorepo grows to dozens or hundreds of packages, running the full test suite on every CI run becomes wasteful when a change only touches one package's leaf dependency, so tools like Turborepo and Nx compute a dependency graph and skip test tasks for packages whose inputs haven't changed, restoring cached results, including coverage output, from a remote cache instead of re-executing Jest. Jest itself also maintains its own transform cache in a directory controlled by the cacheDirectory option, which speeds up repeated local runs by skipping re-transforming unchanged files with Babel or ts-jest, but this cache is process-local and separate from a task runner's cross-machine remote cache.
Cricket analogy: Similar to a broadcaster reusing previously recorded footage for a rain delay instead of re-shooting unaffected match segments, Turborepo's remote cache reuses previous test results for unaffected packages instead of re-running Jest on every CI run.
Jest's own --cache transform cache and a task runner's remote cache solve different problems and neither substitutes for the other: clearing Jest's cache with --clearCache only forces re-transformation of source files locally, while a stale Turborepo or Nx cache hash based on incorrectly declared task inputs can cause CI to skip re-running tests that should have run, silently hiding a real regression.
- Running Jest from a monorepo root risks discovering stale compiled test duplicates in dist or build output unless properly ignored.
- Task runners like Turborepo and Nx often coordinate per-package Jest configs in parallel rather than one root config understanding all workspaces.
- A shared internal preset package, referenced via the preset field, avoids duplicating transform and coverage settings across every package.
- moduleNameMapper can point cross-package imports at sibling packages' src directories so tests see the latest source without a rebuild step.
- Turborepo and Nx skip re-running test tasks for packages whose inputs haven't changed, restoring cached results including coverage.
- Jest's own cacheDirectory transform cache is process-local and distinct from a task runner's cross-machine remote cache.
- Incorrectly declared task inputs can cause a stale remote cache hit that silently skips tests that should have run, hiding regressions.
Practice what you learned
1. Why must a monorepo's root Jest configuration typically exclude dist or build directories?
2. What is a common alternative to one Jest config trying to understand all workspace boundaries in a monorepo?
3. What does referencing a shared preset field in jest.config.js accomplish in a monorepo?
4. Why might moduleNameMapper point a workspace package's import at its src directory instead of its dist output?
5. What distinguishes Jest's own cacheDirectory transform cache from a task runner's remote cache like Turborepo's?
Was this page helpful?
You May Also Like
Jest Configuration: Multi-Project Setups
Learn how to configure Jest's projects array to run multiple test environments and configurations, like unit and integration suites, from a single Jest invocation.
Testing Node.js APIs and Express Routes
Learn how to test Express routes and Node.js API handlers with Jest and supertest, including mocking databases, external calls, and error-handling middleware.
Parameterized Tests with test.each()
Learn how to use Jest's test.each() and describe.each() to run the same test logic against multiple input/output pairs without duplicating code.