Skip to content

0012: Scope Effect diagnostics to Effect code

Keep Effect checks strict without imposing Effect control flow on frameworks

  • Status: Accepted
  • Date: 2026-09-23
  • Decision maker: Trevor Gerhardt

Context

Backend implementations use Effect. React, Next.js, browser harnesses, and the default SDK use ordinary TypeScript interfaces. A global Effect rule set conflicts with those boundaries and with required async Server Actions.

Decision

The workspace pins a compatible TypeScript and Effect toolchain and patches TypeScript and Oxlint at install time. Ordinary lint applies everywhere. Effect diagnostics apply to Effect-owned packages and files. Mixed applications and the SDK use directory conventions to separate Effect modules from framework and Promise adapters.

Dedicated Effect TypeScript projects fail on Effect diagnostics. Mixed projects use scoped Oxlint as their Effect gate. Small reviewed *.node.ts adapters can use Node APIs when Effect platform services cannot preserve the needed semantics. Other Effect-owned files use Effect platform services. A root contract checks the adapter convention.

The Oxlint guide owns file classification and the TypeScript guide owns project configuration.

Consequences

  • New Effect findings block checks only where Effect owns the implementation.
  • Framework and Promise interfaces keep their required control flow.
  • Tool upgrades require compatibility and diagnostic checks.