Should our test setup reflect the framework we ship, or the environment we build in?

[TVW96]

Jest Transformer: next/jest vs ts-jest

Status: Open for Discussion
This document outlines the current state of our Jest setup, what changed, why it changed, and the trade-offs worth discussing before settling on a long-term approach.

---

Background

Our frontend test suite (nsc-events-nextjs) uses Jest as the test runner. Jest requires a transformer — a tool that compiles TypeScript and JSX into plain JavaScript before tests run. This project has two transformers installed, and understanding the difference between them is what this document is about.

---

Where These Dependencies Came From

next (and next/jest)

next is our frontend framework and has been present since the project's initial commit (d4dd851, "initial commit mongo to postgreSQL Migration", Sept 26 2025). Alongside it, jest.config.js was set up to use next/jest — a Jest configuration helper that ships as part of the Next.js package itself.

next/jest is not a separate install. It comes for free with next.

// jest.config.js — original setup
const nextJest = require("next/jest");
const createJestConfig = nextJest({ dir: "./" });
module.exports = createJestConfig(customJestConfig);

ts-jest

ts-jest was also added in the same initial commit as a devDependency in package.json, but it was never wired into jest.config.js. It has been installed and unused since the project began.

// nsc-events-nextjs/package.json
"devDependencies": {
  "ts-jest": "29.2.5"
}

---

What next/jest Actually Does

next/jest is a thin wrapper that pre-configures Jest for Next.js projects. Specifically it:

1. Uses SWC as the transformer — SWC is a Rust-based compiler, significantly faster than Babel. It ships with Next.js as a set of platform-specific native binaries (e.g. @next/swc-darwin-arm64 for Apple Silicon, @next/swc-linux-x64-gnu for Linux).
2. Auto-mocks CSS modules and static file imports — components that import .css files or images work in tests without any extra setup.
3. Inherits Next.js compiler settings — things like absolute imports (@/) are resolved automatically from next.config.js.

The tradeoff is that SWC's native binaries are optional dependencies. npm may skip installing them under certain conditions (platform mismatches, --ignore-optional flags, stripped CI environments), and when the binary is missing, every Jest worker crashes before running a single test.

---

What ts-jest Does

ts-jest is a standalone Jest transformer that compiles TypeScript using the TypeScript compiler (tsc) directly. It:

1. Has no native binaries — it is pure JavaScript/TypeScript, so it installs and runs identically on every platform.
2. Reads tsconfig.json — it respects the project's TypeScript configuration, with the ability to override specific options (e.g. jsx: "react-jsx" for React component support).
3. Requires explicit mocks for non-TypeScript assets — CSS modules and image imports must be mapped to mock files manually.

The tradeoff is that ts-jest is slower than SWC for large test suites, and it requires a small amount of additional configuration.

---

Why the Switch Was Made

The pre-push Husky hook (/.husky/pre-push) and the GitHub Actions workflow (.github/workflows/frontend-ci.yml) both run npm run test:frontend before allowing a push or merge. When the @next/swc-darwin-arm64 binary was absent from a contributor's local node_modules, all 19 test suites failed to start — not because of broken tests, but because the transformer itself could not load.

Since ts-jest was already a declared devDependency and does not depend on any platform binary, it was wired into jest.config.js as the transformer. Two mock files were added to handle the CSS and image imports that next/jest was previously handling automatically:

nsc-events-nextjs/
  __mocks__/
    fileMock.js     ← stubs image/font imports
    styleMock.js    ← stubs CSS module imports
  jest.config.js    ← now uses ts-jest directly

---

Current Configuration

// jest.config.js — current setup
const config = {
  testEnvironment: "jsdom",
  transform: {
    "^.+\\.(ts|tsx|js|jsx)$": [
      "ts-jest",
      {
        tsconfig: { jsx: "react-jsx" },
      },
    ],
  },
  moduleNameMapper: {
    "^@/(.*)$": "<rootDir>/$1",
    "\\.(css|less|scss|sass)$": "<rootDir>/__mocks__/styleMock.js",
    "\\.(gif|ttf|eot|svg|png|jpg|jpeg|webp)$":
      "<rootDir>/__mocks__/fileMock.js",
  },
  coverageProvider: "v8",
  setupFilesAfterEnv: ["<rootDir>/jest.setup.js"],
};

---

Trade-offs at a Glance

	next/jest (SWC)	ts-jest
Trnsform speed	Fast (native Rust binary)	Moderate (TypeScript compiler)
Platform reliability	Depends on optional binary install	Consistent across all platforms
Next.js feature awareness	Built-in	None — plain TypeScript
CSS/image mock setup	Automatic	Manual (2 mock files)
Configuration overhead	Minimal	Low, but explicit
Suitable for CI (Linux)	Yes, if binary installs correctly	Yes, always
Suitable for local dev (Apple Silicon)	Only if @next/swc-darwin-arm64 is present	Yes, always

---

Questions Worth Discussing

1. Is transform speed a concern?
   Currently 385 tests across 19 suites run in ~45 seconds with ts-jest. Would the team benefit from the speed of SWC, or is the current runtime acceptable?

2. Do we test any Next.js-specific APIs?
   next/jest can auto-mock next/router, next/navigation, and next/image. If future tests need these, ts-jest would require manual mocks. Is that on the roadmap?

3. Should the SWC binary be an explicit dependency?
   One option to keep next/jest while fixing reliability is to add @next/swc-darwin-arm64 and @next/swc-linux-x64-gnu as explicit (non-optional) devDependencies. This avoids the missing-binary problem but pins platform-specific packages into package.json.

4. Should @next/swc-darwin-arm64 not being installed be treated as a setup issue?
   The missing binary could be a symptom of contributors running npm install --ignore-optional or a stale node_modules. If the team adds a setup check or documents the correct install process, next/jest could be restored without code changes.

5. Is ts-jest the right long-term choice, or a workaround?
   The current setup works and is portable. But if the project grows and test speed becomes a bottleneck, revisiting SWC-based transforms (either via next/jest with a reliable binary or via @swc/jest as a standalone SWC transformer) is worth considering.