Migrating from V3

Understand what changes between Effect V3 and V4 in terms of diagnostics, and how to configure effect-tsgo for a V4 project.

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

Rule	Category	Description
nonObjectEffectServiceType	Correctness	Ensures Effect.Service types are objects, not primitives
runEffectInsideEffect	Anti-pattern	Suggests using Runtime methods instead of Effect.run* inside Effect contexts
schemaSyncInEffect	Anti-pattern	Suggests using Effect-based Schema methods instead of sync methods inside Effect generators
scopeInLayerEffect	Anti-pattern	Suggests using Layer.scoped instead of Layer.effect when Scope is in requirements
missingEffectServiceDependency	Style	Checks that Effect.Service dependencies satisfy all required layer inputs
schemaUnionOfLiterals	Style	Suggests combining multiple Schema.Literal calls in Schema.Union into a single Schema.Literal

Completions

Completion	Description
contextSelfInClasses	Context.Tag self-type snippets in extends clauses
effectSelfInClasses	Effect.Service / Effect.Tag self-type snippets in extends clauses
rpcMakeClasses	Rpc.make constructor snippet in extends clauses
schemaBrand	brand("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.