Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Effect-TS/tsgo/llms.txt

Use this file to discover all available pages before exploring further.

Effect V4 (codename “smol”) introduces a redesigned service system and removes several APIs that existed in V3. The Effect Language Service detects which version of Effect you have installed and adjusts its diagnostics accordingly — some rules apply only to V3 projects, others only to V4 projects, and many apply to both.

​
How version detection works

The language service reads your installed effect package version from node_modules at startup. You do not need to set any option manually — if effect@4.x is detected, V4-only rules activate and V3-only rules are silently disabled. The reverse applies for V3 projects.
If you are working in a monorepo where different packages use different Effect versions, the version is resolved per tsconfig.json root.

​
Rules that are V3-only

The following diagnostics and completions are disabled automatically when a V4 project is detected. If you see them mentioned in the changelog or documentation, they do not apply to your V4 codebase.

​
Diagnostics

RuleCategoryDescription
nonObjectEffectServiceTypeCorrectnessEnsures Effect.Service types are objects, not primitives
runEffectInsideEffectAnti-patternSuggests using Runtime methods instead of Effect.run* inside Effect contexts
schemaSyncInEffectAnti-patternSuggests using Effect-based Schema methods instead of sync methods inside Effect generators
scopeInLayerEffectAnti-patternSuggests using Layer.scoped instead of Layer.effect when Scope is in requirements
missingEffectServiceDependencyStyleChecks that Effect.Service dependencies satisfy all required layer inputs
schemaUnionOfLiteralsStyleSuggests combining multiple Schema.Literal calls in Schema.Union into a single Schema.Literal

​
Completions

CompletionDescription
contextSelfInClassesContext.Tag self-type snippets in extends clauses
effectSelfInClassesEffect.Service / Effect.Tag self-type snippets in extends clauses
rpcMakeClassesRpc.make constructor snippet in extends clauses
schemaBrandbrand("varName") snippet when dot-accessing Schema in variable declarations

​
Rules that are V4-only

​
outdatedApi — detect renamed or removed APIs

Severity: warning (enabled by default for V4 projects) The outdatedApi diagnostic scans your code for APIs that existed in Effect V3 but have been removed or renamed in V4. When triggered, it identifies the outdated call site and, where possible, suggests the replacement. 
import { Effect } from "effect"

// Example: an API that was renamed in V4
const program = Effect.someV3Api() 
const program = Effect.someV4Replacement()
The exact set of APIs flagged by outdatedApi grows as V4 stabilises. Check the CHANGELOG for additions in each release.

​
serviceNotAsClass — enforce class-based service declarations

Severity: off by default (➖), quick fix available In Effect V4, services are declared using ServiceMap.Service as a class, not as a variable assignment. The serviceNotAsClass diagnostic warns when the variable style is used and offers a quick fix to convert it. 
import { ServiceMap } from "effect"

// V3-style variable declaration (flagged in V4 projects)
const MyService = ServiceMap.Service<MyService>()("MyService", { 
  accessors: true, 
}) 

// V4-style class declaration (correct)
class MyService extends ServiceMap.Service<MyService>()("MyService", { 
  accessors: true, 
}) {}
You can enable this rule at warning or error level in your plugin options: 
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@effect/language-service",
        "diagnosticSeverity": {
          "serviceNotAsClass": "warning"
        }
      }
    ]
  }
}

​
Configuring for a V4 project

1

Install effect-tsgo

Run the guided setup to install and configure @effect/tsgo:
npx @effect/tsgo setup
This adds the plugin entry to your tsconfig.json and installs the binary.
2

Verify Effect V4 is installed

Make sure your project depends on effect@4.x:
npm ls effect
The language service reads this version automatically — no additional configuration is needed to switch between V3 and V4 rule sets.
3

Enable serviceNotAsClass (optional)

The serviceNotAsClass rule is off by default. To surface it as a warning across your project, add it to diagnosticSeverity in your tsconfig.json:
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@effect/language-service",
        "diagnosticSeverity": {
          "serviceNotAsClass": "warning",
          "outdatedApi": "warning"
        }
      }
    ]
  }
}
4

Address outdatedApi warnings

After enabling the plugin, open your editor and look for outdatedApi warnings (yellow underlines). Each warning indicates a V3 API that must be updated. Use the hover tooltip to see the recommended replacement, then apply the change.

​
Common migration patterns

​
Service declarations

The most common change when moving from V3 to V4 is converting service variable assignments to class declarations. 
import { ServiceMap, Effect, Layer } from "effect"

// Before: V3 variable style
interface HttpClient { 
  get: (url: string) => Effect.Effect<Response> 
} 
const HttpClient = ServiceMap.Service<HttpClient>()( 
  "HttpClient", 
  { accessors: true } 
) 

// After: V4 class style
class HttpClient extends ServiceMap.Service<HttpClient>()( 
  "HttpClient", 
  { accessors: true } 
) { 
  get(url: string): Effect.Effect<Response> { 
    return Effect.die("not implemented") 
  } 
}

​
Checking for missing V3-only rules

If you relied on rules like scopeInLayerEffect or runEffectInsideEffect in a V3 project and now want similar protection in V4, check the diagnostics overview for the equivalent V4 rules or patterns.
Most correctness rules (missingEffectContext, missingEffectError, floatingEffect, etc.) work identically in both V3 and V4 — your existing rule configuration carries over automatically.

Build docs developers (and LLMs) love

Get started for freeTalk to us