DEV Community: Janarthanan Soundararajan (Jana)

Monorepo, Turborepo, Modular Monolith, and Microservices: What Actually Changes?

Janarthanan Soundararajan (Jana) — Tue, 25 Aug 2026 18:08:36 +0000

A Turborepo can contain multiple applications under apps/. If those applications can be built and deployed separately, does that mean the system uses microservices?

Not necessarily. Multiple applications in one repository tell us how the source code is organized. Microservices are defined by runtime and operational boundaries.

Consider this small structure:

platform/
├── apps/
│   ├── marketing/
│   └── app/
└── packages/
    └── db/

Is this a monorepo, a modular monolith, or a microservices architecture?

It is clearly a monorepo. It might contain a modular-monolith application. The tree alone, however, cannot prove that any microservices exist.

While formalizing the architecture of SlotSyncro, a portfolio application, I wanted to sharpen how I distinguished these familiar concepts. They are often discussed together, even though each describes a different layer of a system. Placing them at their correct layers turns a broad understanding into a more precise architectural model.

Four concepts at four different layers

Here is the central distinction:

Concept	What it describes	Primary question
Monorepo	Repository organization	Where does the code live?
Turborepo	Task orchestration	How are builds, tests, and other tasks coordinated?
Modular monolith	Internal application design	How is one deployable application divided?
Microservices	Runtime architecture	How are services deployed, scaled, and connected?

Turbopack is related by name, but it solves another problem:

Repository organization → Monorepo
Task orchestration      → Turborepo
Application structure   → Modular monolith
Runtime architecture    → Microservices
Compilation             → Turbopack

Turborepo coordinates tasks across workspaces. Turbopack bundles a Next.js application. These concepts do not occupy the same architectural layer, so they are not direct alternatives.

That is why questions such as “Should I use a monorepo or microservices?” are difficult to answer as stated. A team can use both, either, or neither.

What makes SlotSyncro a monorepo?

A monorepo is one repository that contains multiple related projects. Those projects might be applications, shared libraries, configuration packages, or services. They share Git history and can be changed together, but they can still have separate dependencies, scripts, and release processes.

SlotSyncro currently has this workspace structure:

slotsyncro/
├── apps/
│   ├── marketing/    # Public marketing website
│   └── app/          # Scheduling product
├── packages/
│   └── db/           # Prisma and database infrastructure
├── package.json
├── pnpm-workspace.yaml
└── turbo.json

The examples in this article are based on SlotSyncro, a scheduling product I am creating as a portfolio application. The repository is publicly viewable as a practical implementation reference: SlotSyncro.

This is a monorepo because multiple identifiable projects live in one Git repository. The applications and database package have their own package.json files, while pnpm workspaces connect them. A change to the product and its database package can be reviewed and committed together.

A workspace is one project recognized and managed by the repository's package manager. In this example, apps/app, apps/marketing, and packages/db are separate pnpm workspaces. Each can define its own package name, dependencies, and commands, while using another local workspace as a dependency without publishing it to a package registry.

The monorepo label does not tell us how many production processes exist. It does not mean every folder is independently deployed, every application is a microservice, or every shared file needs its own package.

Turborepo is not required either. A repository can be a monorepo using only pnpm, npm, or Yarn workspaces. Turborepo is an additional task runner, not the feature that makes it a monorepo.

What Turborepo actually does

In this repository, the tools sit roughly in this order:

Git repository
      ↓
pnpm workspaces
      ↓
Turborepo
      ↓
Next.js, Prisma, Vitest, and other workspace tools

The root commands delegate work across the repository. Typical Turborepo commands look like this:

turbo run build
turbo run test
turbo run lint

Turborepo understands workspace dependencies, schedules tasks in the right order, caches successful outputs, avoids repeated work, and can filter execution to selected workspaces. For example, a task graph can ensure that database-client generation runs before dependent application builds.

None of this provides service-to-service communication. Turborepo does not create API gateways, message queues, independent databases, distributed transactions, container orchestration, or production scaling rules.

Turborepo knows that one workspace depends on another. It does not decide whether those workspaces become separate production services.

In current Next.js versions, Turbopack is the default bundler for development and production builds unless Webpack is explicitly selected. The similar names can make the tools sound interchangeable, but their scopes are different: Turborepo operates on the repository's task graph, while Turbopack operates on an application's module graph.

A modular monolith inside a monorepo

Now move one level inward, from the repository to apps/app.

A modular monolith is one deployable application organized into distinct business modules. The modules have defined responsibilities and controlled ways to interact, but they remain part of the same application boundary instead of becoming independently operated network services. It keeps the operational simplicity of a monolith while making internal ownership and dependencies clearer.

SlotSyncro’s current product code is still mainly grouped by technical concerns such as routes, actions, components, and utilities. The accepted direction is to evolve it incrementally into business modules. A possible target shape is:

apps/app/
├── app/                       # Next.js routes
└── modules/                   # Proposed structure
    ├── identity/
    ├── availability/
    ├── booking/
    ├── polls/
    ├── meetings/
    └── notifications/

These would be business modules, not microservices. They would have clear responsibilities and controlled interfaces, but remain part of the same Next.js application, deploy together, and use one PostgreSQL database.

The runtime remains simple:

Monorepo
├── Marketing application
└── Scheduling application ───────── one deployment boundary
    ├── Identity module
    ├── Availability module
    ├── Booking module
    ├── Polls module
    └── Notifications module
                 ↓
             PostgreSQL

The boundaries are architectural, but they are not network boundaries. A booking operation can call availability logic as a typed function and update related state in one local database transaction.

That is the useful middle ground of a modular monolith: explicit ownership without immediately accepting the operational cost of a distributed system. A monolith is not synonymous with unstructured legacy code. It can have deliberate, well-tested internal boundaries.

Folder names are not module boundaries

A booking module might eventually use a small internal structure like this:

modules/booking/
├── domain/
│   ├── booking.ts
│   └── booking-rules.ts
├── application/
│   ├── create-booking.ts
│   └── cancel-booking.ts
├── infrastructure/
│   └── booking-repository.ts
├── ui/
│   └── booking-form.tsx
└── index.ts

The exact folders matter less than the ownership they express. The module’s index.ts can act as its public API:

import { createBooking } from "@/modules/booking";

Code outside the module should avoid reaching through that API into implementation details:

// Avoid reaching into another module's internals.
import { bookingRepository } from
  "@/modules/booking/infrastructure/booking-repository";

Folders help people see the intended boundary, but they do not enforce it. Public APIs, code review, dependency rules, and tests make the boundary real. Modular-monolith architecture depends more on enforced boundaries than on folder names.

Why multiple applications still do not mean microservices

Return to the original two applications:

apps/
├── marketing/
└── app/

marketing presents public product information. app owns authentication, availability, bookings, polls, and other scheduling workflows. They are different user-facing surfaces, and the repository can build them independently.

That still says nothing about the product’s internal business capabilities being independently operated services. Its booking, polls, and notification concerns currently belong to the same product application. No internal network call is required merely because the repository contains two Next.js apps.

“Multiple applications” is a repository observation. “Microservices” is a runtime conclusion.

Even independent deployment of the marketing and product sites would not make either one a microservice architecture. They may simply be two deployable web applications with different purposes.

What would actually create microservices?

Imagine the repository later changed to this:

platform/
├── apps/
│   ├── marketing/
│   ├── web/
│   ├── scheduling-service/
│   ├── billing-service/
│   ├── notification-service/
│   └── background-worker/
└── packages/
    ├── contracts/
    ├── observability/
    └── config/

The names suggest microservices, but the folders still do not prove it. These components become services through meaningful operational independence: they run as separate processes, deploy and scale independently, communicate through APIs or messages, isolate at least some failures, and have intentionally defined business and data ownership.

A simplified runtime might look like this:

┌─────────────────────┐
│   Web application   │  Deployment A
└──────────┬──────────┘
           │ HTTPS
┌──────────▼──────────┐
│ Scheduling service │  Deployment B
└──────────┬──────────┘
           │ MeetingScheduled event
┌──────────▼──────────┐
│Notification service│  Deployment C
└─────────────────────┘

Now the boundaries are also network and deployment boundaries. That creates capabilities such as independent scaling and release ownership, but it also introduces timeouts, retries, message delivery, distributed tracing, versioned contracts, and consistency decisions.

The trade-off is easier to see side by side:

Modular monolith	Microservices
Modules call one another in-process	Services communicate over a network or queue
Usually deployed together	Independently deployable
Easier cross-module transactions	Distributed consistency must be handled
One primary runtime unit	Multiple runtime units
Lower operational complexity	Higher operational complexity
Boundaries enforced in code	Boundaries also enforced by the network

Independent deployment is important, but it is not the whole definition. If several processes must always release together, share unclear data ownership, and cannot fail independently, the system may be a distributed monolith instead.

Microservices are not the inevitable final stage of a successful modular monolith. For SlotSyncro’s current scale and requirements, local calls and transactions are valuable, while independent service operation has not earned its cost.

Turborepo supports either runtime architecture

Turborepo can coordinate a modular-monolith repository:

apps/marketing
apps/app
packages/db
packages/ui       # possible future extraction

It can also coordinate a repository containing services:

apps/web
apps/scheduling-service
apps/notification-service
apps/worker
packages/contracts

In both cases, it can run the complete build or target a workspace:

turbo run build
turbo run build --filter=scheduling-service

The second repository may use microservices because of how those applications run, communicate, and deploy—not because Turborepo launched their build tasks. Turborepo can manage a repository containing microservices, but it does not turn applications into microservices.

A monorepo can therefore contain a marketing application, a modular-monolith product, and several genuine services at the same time. Repository boundaries and runtime boundaries do not need to match one-to-one.

Keep dependency direction clear

One general monorepo rule prevents a great deal of confusion:

Applications may import packages.
Packages must not import applications.
Good: apps/app → packages/db
Bad:  packages/db → apps/app

If packages/db imports application authentication code, the dependency becomes circular:

apps/app → packages/db → apps/app

The package is no longer reusable infrastructure; it secretly depends on one consumer. Ownership becomes unclear, and isolated testing becomes harder.

For example, database infrastructure should not retrieve application-specific session context:

// Bad: packages/db knows about an application's authentication.
import { getCurrentUser } from "../../apps/app/auth";

Instead, the database package can expose infrastructure without importing from an application:

// packages/db
export { db } from "./client";

The booking module can own its product-specific query while depending on that infrastructure:

// apps/app/modules/booking/infrastructure/booking-repository.ts
import { db } from "@slotsyncro/db";

export function findBookings(userId: string) {
  return db.booking.findMany({ where: { userId } });
}

The application layer supplies the authentication context it owns:

// apps/app/modules/booking/application/list-my-bookings.ts
const user = await getCurrentUser();
const bookings = await findBookings(user.id);

This principle applies to monorepos generally. Turborepo can understand a dependency graph, but it cannot decide whether that graph represents sensible ownership.

When should a module become a package?

Once developers see a packages/ directory, it is tempting to move every cleanly named capability into it. That usually creates boundaries before there is evidence for them.

Application module	Shared package
Belongs to one application	Lives outside a specific application
Represents a product capability	Provides a reusable capability
May depend on application conventions	Should expose a stable interface
Usually has one consumer	Often has multiple consumers
Deploys with its application	May be consumed by several applications

For example, SlotSyncro should begin with booking behavior close to its only consumer:

apps/app/modules/booking/

It should not create packages/booking merely to make the repository tree look more sophisticated. Keeping code inside its only consumer is not poor architecture. It is often the clearest expression of ownership.

Possible future extractions include:

packages/
├── domain/    # Framework-independent scheduling rules
├── email/     # Shared templates or rendering infrastructure
└── ui/        # Components genuinely shared by both applications

These are proposals, not current SlotSyncro workspaces. packages/domain becomes useful if scheduling calculations need to run in the product, a worker, and isolated tests. packages/email becomes useful after multiple notification workflows need common rendering. packages/ui becomes especially useful when the marketing and product applications share a maintained design system, or when the component system has meaningful independent development and testing value.

A practical extraction test

A package should have at least one strong justification, and preferably more than one.

More than one consumer

Two applications or runtimes need the same capability. Reuse is real, not predicted from one similar-looking component.

Framework-independent domain value

Scheduling calculations can run without React, Next.js, Prisma, or a provider SDK. That isolation makes the code easier to reuse and reason about.

Stable inputs and outputs

The capability exposes a small, intentional API instead of importing application internals. If its interface changes with every feature, extraction may be premature.

Independent testing value

Its behavior can be tested meaningfully without starting the complete application. This is especially useful for scheduling, timezone, or consensus rules.

Different build or deployment concerns

Database generation, email rendering, shared contracts, or worker code may need distinct tasks. A workspace boundary can make those workflows explicit.

Do not extract code merely because packages/ makes the repository look more sophisticated. Extraction should clarify ownership or enable a real workflow.

A decision framework

When the terminology starts to blur, I return to these questions:

Do multiple related projects need to live together?
→ Consider a monorepo.
Do you need caching and coordinated workspace tasks?
→ Consider Turborepo.
Does one deployable application need stronger internal boundaries?
→ Use a modular monolith.
Does one capability require independent deployment, scaling,
failure isolation, data ownership, or team autonomy?
→ Consider extracting a service.
Is some code used by only one application?
→ Keep it close to that application for now.

This sequence avoids using a runtime solution for a repository problem—or creating a network boundary when a code boundary is enough.

Repository note: SlotSyncro is a public portfolio and reference repository, not an open-source project or starter template. Some modules and packages discussed in this article are architectural proposals and do not exist in the current implementation.

The complete mental model

A monorepo organizes where code lives.

A modular monolith organizes boundaries inside one application.

Microservices define independently operated runtime boundaries.

Turborepo coordinates tasks across the repository.

Turbopack compiles a Next.js application.

The number of folders under apps/ does not determine the runtime architecture. Deployment, communication, scaling, and ownership boundaries do.

I thought Vite broke my 3D physics. It actually taught me how tree-shaking really works.

Janarthanan Soundararajan (Jana) — Sun, 16 Aug 2026 09:05:54 +0000

In modern browser-based game development, every kilobyte matters. Larger JavaScript payloads increase download, parse, compile, and execution times, which can delay interactivity—especially on slower devices or networks.

To enforce a strict, lightweight architecture for our latest project at techaaroorian-games, we utilized Babylon's ES module packages (@babylonjs/core). For a modular application, this structure gives the bundler as much opportunity as possible to remove code the application doesn't actively use.

We set up Vite, TypeScript, Babylon.js, and the Havok WebAssembly physics engine.

Then, the engine crashed.
Error: `No Physics Engine available.`

Here is the debugging story of why our physics vanished, and what it teaches us about modern web bundlers.

1. The Simple Tree-Shaking Model

To understand why my game crashed, I had to look at how modern bundlers view our code. Vite uses Rolldown for its production builds—it doesn't read our minds; it reads the module graph.

Is the code reachable and needed? → Keep it.
Can the bundler safely determine it's unnecessary? → Remove it.

But what happens when a module doesn't export an API you need to call, but instead contains module-level registration code you need to run?

2. The Wasm Trap

My first hurdle wasn't even tree-shaking; it was dependency optimization. My terminal completely froze when I tried to start the development server.

@babylonjs/havok ships JavaScript alongside WebAssembly assets, and in my setup, Vite's dependency optimization stalled while processing the package.

I fixed it by telling Vite not to pre-bundle that dependency:

// vite.config.ts
export default defineConfig({
  optimizeDeps: { 
    exclude: ["@babylonjs/havok"] 
  },
});

This lets Vite handle the package outside the dependency pre-bundling step.

With the server finally running, I expected to see my 3D sphere bouncing with gravity. Instead, I got a blank canvas and the fatal error: No Physics Engine available.

3. The "Aha!" Moment: Vite Didn't Break My Physics

Vite didn't break my physics. It exposed an architectural design I didn't know existed.

To keep base payloads lightweight, highly optimized frameworks separate their pure implementation logic from their runtime registration.

Because I only imported the core Scene and Mesh builders, I never directly referenced the physics module's exported API. My import graph didn't establish a need for that registration module to execute. Because its runtime registration wasn't reachable through the imports I had written, the production build could treat it as unnecessary.

The physics code wasn't missing because it was broken. It was missing because its only purpose was to execute registration code, and I didn't tell my bundler that mattered!

4. The Fix: Side-Effect Imports

To fix this, I had to learn the difference between asking a bundler for an API versus asking it for an action.

The Normal Import:

import { Mesh } from "@babylonjs/core";
// Translation: "I need to use the Mesh API."
// Bundler trace: API is used, preserve the module.

The Side-Effect Import:

import "@babylonjs/core/Physics/physicsEngineComponent";
// Translation: "I don't need an exported API from this module, but I do need its module-level registration code to execute."

By adding that single side-effect import, the module executes immediately upon loading. It performs the registration necessary for Babylon's physics functionality to be available at runtime, while still allowing the bundler to aggressively tree-shake everything else.

The Result

The Big Lesson

As I continue building out techaaroorian-games, this completely changed how I look at build tools.

Static dependency → Bundler can trace it → Keep what's reachable
Module-level side effect → Execution itself matters → Make that dependency explicit

Tree-shaking isn't magic. It's static analysis. And once I understood that, "unused code" became a much more interesting concept. The bundler isn't trying to understand what my game means; it is analyzing what my module graph tells it.

(I am documenting my whole journey learning WebGPU and game dev. You can clone the full working engine setup we built today in the techaaroorian-games GitHub repository!)

The DOM Is Lying to Your Types: 3 Subtle React + Zod Validation Traps

Janarthanan Soundararajan (Jana) — Thu, 13 Aug 2026 06:38:47 +0000

A common production stack for React forms is React Hook Form for client-side state, Zod for schema validation, and Next.js Server Actions for the backend mutation.

It feels incredibly robust. But beneath these excellent tools, a subtle friction point is waiting to corrupt your data: Native form values are transport-oriented, not domain-oriented.

Prefer a visual explanation? https://youtu.be/eyE8JeGp2CI?si=s9s4yoNKM4BeuvC1

Even when the browser exposes typed helpers like input.valueAsNumber or input.checked, the raw values crossing a form boundary rarely match your application's domain model directly. React Hook Form can help normalize some primitives at registration (e.g., { valueAsNumber: true }), but this doesn't eliminate the need for boundary validation: NaN, empty values, optional semantics, and unexpected server-side inputs still require explicit handling.

When engineers rush to bridge the gap between transport data and strict TypeScript domain logic, it’s incredibly easy to implement "quick fixes" (like Zod's z.coerce) that make the TypeScript compiler happy but introduce silent data corruption.

To build robust systems, we need to internalize a core architectural principle:
Validation ≠ Type Conversion ≠ Normalization.

Look at the modern form pipeline:

DOM
 ↓
React Hook Form / FormData (Transport Representation)
 ↓
Normalization (Where "30" becomes 30)
 ↓
Validation (Does 30 meet our business rules?)
 ↓
Domain Value (Strictly Typed)
 ↓
Persistence (Database)

Whether you pull data from React Hook Form state or native FormData, your transport representation is limited. It contains strings and File objects, while missing fields are represented by the absolute absence of an entry.

As engineers, our golden rule at the normalization boundary should be: Don't ask "How do I make Zod accept this?" Ask "What does this external value actually mean in my domain?"

Here are three subtle data-boundary traps in the React/Zod ecosystem that happen when those responsibilities blur, and how to design reliable pipelines to prevent them.

Trap 1: The Number Coercion "Zero-Bypass" (Semantic Loss)

The Scenario: You are building a scheduling app and have an optional "Buffer Time" input (<input type="number" name="buffer" />). Because the DOM sends a string, z.number().optional() fails. To fix it, you reach for Zod's coercion API.

// ❌ The Trap
const schema = z.object({
  bufferTime: z.coerce.number().optional()
});

The Actual Problem: This isn't just a type error; it's semantic data loss.
In JavaScript, Number("") evaluates to 0. If a user leaves the input blank because they don't want a buffer, Zod intercepts the empty string, coerces it to 0, and validates it. Because 0 is a valid number, the .optional() check is bypassed entirely.

User Intent	DOM Input	Naive Coercion	Real Problem
No buffer configured	`""`	`0`	Semantic Loss
Explicit 0 minutes	`"0"`	`0`	-

You just erased the semantic distinction between "not provided" (undefined) and "explicitly provided as zero minutes" (0).

The Fix:
Define explicit normalization semantics using z.preprocess() before Zod attempts to validate. Crucially, if the user submits garbage data (like "banana"), we must not silently swallow it—we pass it through so z.number() can properly reject it.

// ✅ Explicit Normalization
const optionalNumberSchema = z.preprocess((val) => {
  // 1. Preserve the semantic meaning of "empty"
  if (val === "" || val === null || val === undefined) {
    return undefined;
  }

  // 2. Safely attempt conversion
  if (typeof val === "string" && val.trim() !== "") {
    const parsed = Number(val);
    return Number.isNaN(parsed) ? val : parsed; // Pass bad data through
  }

  return val;
}, z.number().int().min(0).optional());

(Note: Normalization answers "What value is this?" by intentionally accepting JavaScript's flexible numeric string syntax, like "+30". If your domain requires stricter constraints—for example, whole integers only—you enforce that as a **Validation* rule: z.number().int().min(0)).*

Trap 2: The Boolean Checkbox Nightmare

The Scenario: You have a checkbox for an event setting (<input type="checkbox" name="isPrivate" />). You grab the value from React Hook Form or FormData and pass it to Zod.

// ❌ The Trap
const schema = z.object({
  isPrivate: z.coerce.boolean()
});

The Actual Problem: Native HTML checkboxes do not submit false when unchecked; the field is omitted entirely. Calling formData.get("isPrivate") therefore returns null.

Furthermore, if you are passing JSON payloads from a client UI, passing the string "false" through Boolean("false") actually evaluates to true (because it's a non-empty string). Zod's z.coerce.boolean() is blind to your domain intent.

The Fix:
Don't use arbitrary form strings for boolean coercion. Normalize the transport representation explicitly, and—just like with numbers—don't silently swallow invalid data.

// ✅ Explicit Normalization
const checkboxSchema = z.object({
  isPrivate: z.preprocess((val) => {
    // Recognize explicit truthy transport values
    if (val === "on" || val === "true" || val === true) return true;

    // Recognize explicit falsy transport values
    if (val === "false" || val === false || val == null) return false;

    // Let unexpected values pass through so z.boolean() can catch and reject them!
    return val; 
  }, z.boolean())
});

This guarantees that expected inputs map cleanly to true or false, but if a bad actor or a bug sends "banana", it reaches z.boolean() and gets properly rejected. Unknown ≠ false. Normalization should not silently destroy information.

Trap 3: The Timezone Date Parse (Ambiguous Instants)

The Scenario: A user selects a date and time for an event using <input type="datetime-local" />. It outputs a string like "2026-08-15T09:00".

// ❌ The Trap
const schema = z.object({
  startTime: z.coerce.date()
});

The Actual Problem: A JavaScript Date object represents an absolute instant in time (milliseconds since the epoch). But a user's selection of "August 15, 09:00" is a local wall-clock time.

If a user in New York submits "2026-08-15T09:00" and the server interprets the value using its own runtime timezone, the application has created an absolute instant without knowing which timezone the user intended. You've created an ambiguous point in time.

(Note: This is one of the exact problems the JavaScript Temporal proposal is designed to model explicitly: separating a PlainDateTime from a ZonedDateTime.)

The Fix:
Never parse localized date strings natively in your schema without explicitly capturing and applying the timezone context.

// ✅ The Fix
const schema = z.object({
  // Accept the raw wall-clock time string (e.g., "2026-08-15T09:00")
  localTime: z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/),
  // Accept the user's explicit timezone (e.g., "America/New_York")
  timeZone: z.string() 
}).transform((data) => {
  // Explicitly combine the wall-clock time and timezone 
  // into an absolute UTC instant before saving to the database
  return {
    absoluteUtcInstant: convertToUtcInstant(data.localTime, data.timeZone)
  };
});

The Takeaway

Validation isn't just about rejecting invalid input. At application boundaries, it's also where we define how external, untyped representations officially become typed domain values.

By explicitly separating normalization from validation—and paying attention to semantic zero-bypasses, truthy strings, and wall-clock ambiguity—you can build resilient systems that prevent data corruption before it ever reaches your database.

Why Vite Asked Me to Choose Between Oxlint and ESLint

Janarthanan Soundararajan (Jana) — Sat, 08 Aug 2026 10:39:44 +0000

While initializing a new Vite project (npx create-vite), I hit an interactive CLI prompt that paused my standard workflow:

◆ Which linter to use?
  ● Oxlint
  ○ ESLint

Having relied on ESLint as my default linter for years, this piqued my curiosity. The filled bullet (●) wasn't a formal endorsement from Vite—it was simply where the CLI cursor landed—but it made me pause. Why is Vite offering Oxlint alongside ESLint, and when does it make sense to use it?

Here are my first impressions after looking into what Oxlint is, how it works under the hood, and how I plan to test it out.

❓ Why Is Vite Offering Oxlint?

Vite doesn't recommend Oxlint over ESLint—it simply presents both as first-class options during project creation. Given the growing adoption of native tooling such as SWC, Biome, and Rolldown, adding Oxlint feels consistent with the broader direction of the frontend ecosystem, while still leaving the choice to developers.

Rather than forcing one choice, Vite simply lets developers decide which workflow best fits their needs.

🔍 What is Oxlint?

From my preliminary research, Oxlint is a linter developed as part of the Oxc (Oxidized Compiler) project.

The core difference seems to be the engine: while ESLint runs on Node.js/JavaScript, Oxlint is written in Rust. Because Oxlint is a native executable rather than a JavaScript package running inside Node.js, it can reduce startup overhead and take advantage of parallel execution on modern CPUs.

Rather than trying to replace every custom rule or plugin in the JavaScript ecosystem on day one, Oxlint's current focus appears to be catching common correctness bugs, React hook pitfalls, and type safety issues with minimal setup overhead.

⚔️ How They Seem to Compare

Here is a high-level snapshot based on the documentation and early community feedback I've gathered so far:

Metric / Feature	ESLint	Oxlint
Runtime Engine	Node.js / JavaScript	Rust (Oxidized)
Execution Speed	Varies by project size, plugins, and custom rules	Official Oxlint benchmarks report significantly faster execution than ESLint, and early community feedback has generally reflected similar experiences, though results depend on the project.
Setup & Config	Requires `eslint.config.js`	Designed around sensible zero-config defaults
Plugin Ecosystem	Very mature and extensive	Smaller plugin ecosystem, with built-in support for many common React, TypeScript, JSX, and Jest rules
Primary Value	Deep customization & strict team policies	Fast local feedback and low initial setup friction

⚡ Why the Speed Pitch Caught My Eye

What made me want to investigate Oxlint further is the promise of shorter developer feedback loops.

In past projects, running pre-commit hooks (husky / lint-staged) or saving files during local hot reloading (HMR) sometimes created a small delay while validating code:

# Typical local feedback loop:
# 1. Save or stage a file.
# 2. Run the linting process.
# 3. Wait for rule validation before moving on.

If Rust-based linters can make that validation step feel nearly instant during active coding, that could be a subtle but nice improvement in daily flow. I'm curious to see if that holds true as my project grows from a fresh scaffold into a complete application.

🏗️ The Hybrid Idea I'm Curious to Try

As I read through discussions on how developers are approaching this, one approach I came across repeatedly was a hybrid setup:

For local dev & pre-commit hooks: Use Oxlint as a lightweight frontline defender to catch common mistakes instantly without slowing down commits.
For CI/CD pipelines: Keep ESLint running in GitHub Actions if complex, custom ESLint plugins or team-wide policies are required later on.

// package.json - Conceptual hybrid setup I may experiment with
{
  "scripts": {
    // Frontline check for local HMR & pre-commit hooks
    "lint:fast": "oxlint --deny-warnings",
    // Deep structural audit for CI/CD pipelines
    "lint:ci": "eslint ."
  }
}

🧪 Next Steps & What I'm Testing Next

I decided to select Oxlint for this new Vite build as an initial experiment. Since this is a brand-new project, it felt like a good opportunity to evaluate a newer tool without worrying about migrating an existing lint configuration.

Right now, the codebase is in its early stages, so getting started required virtually no configuration. As I build out components, integrate state management, and add visualizations (like D3 charts), I'm planning to observe:

How well Oxlint catches real React/TypeScript errors during active development.
Whether I run into any rule limitations that force me to bring ESLint back into the loop.

I'll be keeping notes as the project develops and might share a follow-up post with actual hands-on impressions once the site is fully built!

Update: If my experience changes after building a larger React application, I'll publish a follow-up comparing Oxlint and ESLint with real-world usage rather than first impressions.

Fixing Vitest CI Worker Crashes by Switching from jsdom to happy-dom

Janarthanan Soundararajan (Jana) — Fri, 07 Aug 2026 10:43:45 +0000

Our Vitest suite passed every time locally, but GitHub Actions failed before executing a single test. Instead of failed assertions, every test worker crashed during startup, leaving us with 0% coverage and a broken CI pipeline.

After narrowing the issue down to our test environment, we replaced jsdom with happy-dom. That change resolved the worker crashes in our environment and restored a stable GitHub Actions pipeline.

Environment Context

To help determine if this applies to your setup, here is the stack where we encountered this:

Framework: Next.js (App Router)
Testing: Vitest, @testing-library/react
Package Manager: pnpm (Workspace / Monorepo)
CI Environment: GitHub Actions (ubuntu-latest, Node.js 20)

1. The Error: Unhandled Worker Failures in CI

During the pnpm --filter app test:coverage step in GitHub Actions, Vitest failed immediately upon initializing the worker pool:

Vitest caught 7 unhandled errors during the test run.

⎯⎯⎯⎯⎯⎯ Unhandled Error ⎯⎯⎯⎯⎯⎯⎯
Error: [vitest-pool]: Failed to start forks worker for test files /apps/app/__tests__/poll.test.ts.

Caused by: TypeError: webidl.util.markAsUncloneable is not a function
 ❯ new CacheStorage ../node_modules/jsdom/node_modules/undici/lib/web/cache/cachestorage.js:20:17
 ❯ Object.<anonymous> ../node_modules/jsdom/node_modules/undici/index.js:179:25
 ❯ Object.<anonymous> ../node_modules/jsdom/lib/api.js:12:33

 Test Files  no tests
      Tests  no tests
     Errors  7 errors

ERROR: Coverage for lines (0%) does not meet global threshold (80%)

If you encounter errors such as webidl.util.markAsUncloneable is not a function or Failed to start forks worker in a vitest-pool setup, the problem may lie in your test environment's dependency tree rather than in your test code.

2. The Investigation

At first, we assumed one of the test files was failing or throwing an uncaught exception.

But the stack trace told a different story. None of the 7 test files had actually started executing. Every failure occurred while Vitest was initializing worker processes, which meant the problem was happening before our application code even loaded.

The stack trace pointed directly into jsdom's internal undici dependency during worker initialization (jsdom/node_modules/undici/lib/web/cache/cachestorage.js). Rather than a bug in our application code, this suggested an environment-level compatibility issue involving the test environment rather than our application code.

Beyond initial loading issues, jsdom emulates a large portion of standard browser behavior and maintains a detailed DOM object model. In resource-constrained CI environments (like standard Linux runners in GitHub Actions), this extra memory footprint can increase resource usage and startup time, especially during coverage runs.

We could have spent more time investigating the exact dependency mismatch, but since our tests only required standard DOM APIs, switching to a lighter implementation was the simpler and lower-risk solution.

3. The Switch: Moving to `happy-dom`

Why `happy-dom` Worked

Unlike jsdom, happy-dom focuses specifically on implementing the browser APIs commonly needed by modern frontend unit tests (such as React synthetic events and DOM queries) rather than reproducing every full browser behavior. Because of its smaller scope, happy-dom generally starts faster and has a lower resource footprint than jsdom for many component-testing scenarios, making it a good fit for React component testing in Vitest.

Step 1: Replace Dependencies

pnpm --filter app remove jsdom
pnpm --filter app add -D happy-dom @vitest/coverage-v8

Step 2: Update Vitest Configuration

Update vitest.config.ts to use happy-dom:

import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
  test: {
    environment: 'happy-dom',
    globals: true,
    setupFiles: ['./vitest.setup.ts'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html', 'json-summary'],
      exclude: [
        'node_modules/',
        '.next/',
        'vitest.config.ts',
        'vitest.setup.ts',
        '**/*.d.ts',
      ],
    },
  },
});

Step 3: Recommended Test Setup

In vitest.setup.ts, ensure component trees are explicitly unmounted after each test block:

import '@testing-library/jest-dom/vitest';
import { cleanup } from '@testing-library/react';
import { afterEach } from 'vitest';

afterEach(() => {
  cleanup();
});

Note: This cleanup setup was not required to fix the worker initialization issue, but we keep it to ensure each test runs with a clean DOM and to avoid state leaking between tests.

4. Results

Metric	Before (`jsdom`)	After (`happy-dom`)
Worker Initialization	❌ Failed across all 7 test files	✅ All workers started successfully
Code Coverage	❌ 0% (Threshold failure)	✅ Coverage generated successfully
Pipeline Status	❌ CI failed consistently	✅ CI passed consistently
Execution	❌ Failed during worker initialization	⚡ Entire suite finished in ~15 seconds

While we didn't identify the exact package combination that triggered the incompatibility, replacing jsdom removed the issue entirely for our CI environment, making further investigation unnecessary for our use case.

5. When Should You Keep `jsdom`?

Every tool comes with trade-offs, and happy-dom isn't a 1:1 replacement for every project:

Keep jsdom if: Your tests depend on advanced browser APIs that happy-dom doesn't fully implement, or you are testing behavior that closely mirrors browser layout and parsing internals.
Use happy-dom if: You are primarily running React, Vue, or Svelte component tests with @testing-library, where rendering components and asserting on DOM output is all you need.

6. Lessons Learned & Takeaways

Key Takeaway: Before changing test code, check whether the failure occurs before the first test executes. If worker initialization fails, the root cause is often the test environment, dependency graph, or runtime—not your application logic.

The lesson wasn't that happy-dom is universally better than jsdom.

It was that your test environment should match your testing needs. For our React component tests, a lightweight DOM implementation was enough—and choosing the simplest test environment that satisfied our requirements made the CI pipeline both faster and more reliable.

Sometimes the quickest path to a stable CI pipeline isn't finding the perfect root cause—it's choosing the simplest tool that satisfies your testing requirements.

Should You Unit Test Glue Files? A Practical Decision Matrix

Janarthanan Soundararajan (Jana) — Thu, 06 Aug 2026 05:57:22 +0000

Have you ever spent an entire afternoon writing a unit test for a five-line setup component?

You mock three context providers, an Auth.js session hook, and a router adapter—only to assert that a button renders in the DOM. At that point, it’s worth asking:

Are we testing our application, or just testing our mocks?

In React applications, not every file benefits equally from isolated unit tests—but figuring out which ones those are isn't always obvious. Over time, I’ve moved away from chasing high coverage numbers for its own sake toward a more pragmatic framework for balancing unit tests (with Vitest or Jest) and End-to-End integration tests (with Playwright).

Here is how I think about testing wiring code without grinding developer velocity to a halt.

What Are "Glue Files"?

"Glue files" isn't an official software engineering term. It's simply the name I use for files whose primary responsibility is connecting parts of an application rather than implementing business logic.

Most React developers will recognize these files instantly in their codebases:

Entry & Wiring Files: main.tsx, App.tsx, providers.tsx, layout.tsx
Routing & Client Config: router.tsx, queryClient.ts, middleware.ts
Store Initialization: store.ts (when primarily configuring Redux/Zustand rather than implementing custom middleware or complex state logic)
Auth & Localization Wrappers: <SignInButton/> wrappers around Auth.js or Firebase, and language switchers wrapping next-intl
UI Primitives: Base design system elements (components/ui/* built over Radix UI or Tailwind primitives)

These files act as the "mortar" holding your external dependencies, global state trees, and visual layout together.

The Hidden Cost of Unit Testing Pure Glue Files

Writing unit tests for pure domain functions is fast and rewarding. Writing unit tests for glue files often leads to three common headaches:

1. 90% Mock Setup, 10% Actual Assertion

To unit test a file that simply instantiates a client or wires up a third-party hook, you often end up writing dozens of lines of mock setup code just to test a few lines of JSX:

// tests/AuthButton.test.tsx
import { render, screen } from '@testing-library/react';
import { vi } from 'vitest';

// Mocking external library hooks and routers
vi.mock('next-auth/react', () => ({
  useSession: () => ({ data: null, status: 'unauthenticated' }),
  signIn: vi.fn(),
}));

vi.mock('next/navigation', () => ({
  useRouter: () => ({ push: vi.fn() }),
}));

test('renders sign-in button', () => {
  render(<SignInButton />);
  expect(screen.getByText('Sign In')).toBeInTheDocument();
});

When 90% of a test file consists of vi.mock(), you aren't really testing application behavior—you are mostly testing your ability to write mocks.

2. High Fragility with Low Return

Because these tests are tightly bound to the internal signatures of third-party libraries, updating a dependency often breaks your unit tests even if the actual user-facing feature works perfectly fine.

3. Testing Framework Behavior Instead of Your Logic

Maintainers of packages like TanStack Query, Radix UI, or React Router already maintain extensive unit test suites. Writing unit tests to verify that <QueryClientProvider client="{queryClient}"> passes down context means you're often verifying framework behavior rather than your own application's logic.

The Decision Matrix: Does This File Make Decisions?

In my experience, asking this single question eliminates most debates about whether a file deserves unit tests: Does this file make decisions?

┌─────────────────────────────────────┐
│    Does this file make decisions?   │
└─────────────────────────────────────┘
                 │
        ┌────────┴────────┐
        │                 │
       Yes               No
        │                 │
        ▼                 ▼
┌───────────────┐   ┌────────────────────┐
│   Unit Test   │   │ Is it wiring only? │
│ Vitest / Jest │   └─────────┬──────────┘
└───────────────┘             │
                       ┌───────┴────────┐
                       │                │
                      Yes              No
                       │                │
                       ▼                ▼
             Verify Through       Re-evaluate File
             Integration / E2E    Responsibilities
              (Playwright)

Seeing the Matrix in Practice

Let’s look at two concrete examples to see how this decision rule works in real code.

Example 1: `queryClient.ts`

Pure Wiring (Skip Unit Tests):

import { QueryClient } from '@tanstack/react-query';

export const queryClient = new QueryClient();

Decision Check: Does this file make decisions? No.
Strategy: Skip unit testing. Verify data fetching behavior through Playwright integration or end-to-end smoke tests.

Contains Decision Logic (Unit Test It!):

import { QueryClient } from '@tanstack/react-query';

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      retry: process.env.NODE_ENV === 'production' ? 3 : false,
    },
  },
});

Decision Check: Does this file make decisions? Yes. It evaluates the current environment to choose retry behavior.
Strategy: Write a Vitest unit test to verify that retries evaluate correctly across environments.

Example 2: `router.tsx`

Static Routes (Skip Unit Tests):

export const router = createBrowserRouter([
  { path: '/', element: <Home /> },
  { path: '/dashboard', element: <Dashboard /> },
]);

Decision Check: Does this file make decisions? No. It's purely declarative static wiring.

Conditional Routing (Unit Test It!):

export function getAppRoutes(userRole: string) {
  return createBrowserRouter([
    { path: '/', element: <Home /> },
    ...(userRole === 'admin' ? [{ path: '/admin', element: <AdminPanel /> }] : []),
  ]);
}

Decision Check: Does this file make decisions? Yes. It computes routes based on role permissions.

Quick Checklist: When Should You Unit Test a Glue File?

My default rule is: In most cases, I don't unit test pure glue files because they don't contain business logic.

However, a glue file becomes worth unit testing as soon as it:

✅ Contains branching or conditional logic (if / else, ternary checks)
✅ Transforms configuration dynamically at runtime
✅ Chooses behavior based on environment variables
✅ Applies feature flags or user permissions
✅ Has custom calculation logic that can fail independently

Otherwise, skip the unit test and verify it at the integration or E2E level.

Final Thoughts

This isn't a rigid rule—it's a heuristic. Every codebase is different, and your testing strategy should reflect your team's priorities, risk tolerance, and architecture.

Coverage tells you how much code executed. Good tests tell you how confident you should be when shipping.

If there's one takeaway to keep in mind when designing your test suite, it's this:

Code deserves tests in proportion to the decisions it makes.
Business logic makes decisions.
Glue code makes connections.
Test them accordingly.