Plugin options

Complete reference for all @effect/language-service plugin options in tsconfig.json.

Configure the Effect Language Service by adding options to the @effect/language-service plugin entry in your tsconfig.json. All options are optional and fall back to their documented defaults.

Full configuration example

tsconfig.json

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@effect/language-service",
        // Maps rule names to severity levels. Use {} to enable diagnostics with rule defaults. (default: {})
        "diagnosticSeverity": {},
        // When false, suggestion-level Effect diagnostics are omitted from tsc CLI output. (default: true)
        "includeSuggestionsInTsc": true,
        // When true, suggestion diagnostics do not affect the tsc exit code. (default: true)
        "ignoreEffectSuggestionsInTscExitCode": true,
        // When true, warning diagnostics do not affect the tsc exit code. (default: false)
        "ignoreEffectWarningsInTscExitCode": false,
        // When true, error diagnostics do not affect the tsc exit code. (default: false)
        "ignoreEffectErrorsInTscExitCode": false,
        // When true, disabled diagnostics are still processed so directives can re-enable them. (default: false)
        "skipDisabledOptimization": false,
        // Configures key pattern formulas for the deterministicKeys rule.
        "keyPatterns": [
          {
            "target": "service",
            "pattern": "default",
            "skipLeadingPath": ["src/"]
          },
          {
            "target": "custom",
            "pattern": "default",
            "skipLeadingPath": ["src/"]
          }
        ],
        // Enables matching constructors with @effect-identifier annotations. (default: false)
        "extendedKeyDetection": false,
        // Minimum number of contiguous pipeable transformations to trigger missedPipeableOpportunity. (default: 2)
        "pipeableMinArgCount": 2,
        // Mermaid rendering service for layer graph links. (default: "mermaid.live")
        "mermaidProvider": "mermaid.live",
        // When true, suppresses external Mermaid links in hover output. (default: false)
        "noExternal": false,
        // How many levels deep the layer graph extraction follows symbol references. (default: 0)
        "layerGraphFollowDepth": 0,
        // Controls which effectFnOpportunity quickfix variants are offered. (default: ["span"])
        "effectFn": ["span"],
        // When true, suppresses redundant return-type inlay hints on Effect generator functions. (default: false)
        "inlays": false,
        // Package names allowed to have multiple versions without triggering duplicatePackage. (default: [])
        "allowedDuplicatedPackages": [],
        // Package names that should prefer namespace imports. (default: [])
        "namespaceImportPackages": [],
        // Package names that should prefer barrel named imports. (default: [])
        "barrelImportPackages": [],
        // Package-level import aliases keyed by package name. (default: {})
        "importAliases": {},
        // Controls whether named reexports are followed at package top-level. (default: "ignore")
        "topLevelNamedReexports": "ignore"
      }
    ]
  }
}

Diagnostic control

diagnosticSeverity · Record<string, Severity> · default: "{}"

Maps rule names to severity levels, overriding each rule’s built-in default. Set to {} to enable all diagnostics at their defaults. Valid severity values are "error", "warning", "suggestion", "message", and "off".

"diagnosticSeverity": {
  "floatingEffect": "warning",
  "strictEffectProvide": "error",
  "globalFetch": "off"
}

includeSuggestionsInTsc · boolean · default: "true"

When false, suggestion-level Effect diagnostics are omitted from tsc CLI output. LSP and other editor flows are not affected.

ignoreEffectSuggestionsInTscExitCode · boolean · default: "true"

When true, Effect suggestion and message-category diagnostics do not affect the tsc process exit code. The diagnostics are still reported; they just won’t cause a non-zero exit.

ignoreEffectWarningsInTscExitCode · boolean · default: "false"

When true, Effect warning-category diagnostics do not affect the tsc process exit code.

ignoreEffectErrorsInTscExitCode · boolean · default: "false"

When true, Effect error-category diagnostics do not affect the tsc process exit code.

skipDisabledOptimization · boolean · default: "false"

When true, diagnostics that are globally disabled are still processed so that per-line or per-section @effect-diagnostics directive comments can re-enable them locally. Enabling this option has a performance cost proportional to the number of disabled rules.

Key detection

keyPatterns · KeyPattern[]

Configures the key pattern formulas used by the deterministicKeys diagnostic. Each entry is an object with the following fields:

Field	Type	Description
target	"service" | "custom"	Whether the pattern applies to service identifiers or custom identifiers.
pattern	string	The formula for deriving the key string. Use "default" for the built-in derivation.
skipLeadingPath	string[]	Path prefixes to strip when computing the key (e.g. ["src/"]).

Default:

"keyPatterns": [
  { "target": "service", "pattern": "default", "skipLeadingPath": ["src/"] },
  { "target": "custom",  "pattern": "default", "skipLeadingPath": ["src/"] }
]

extendedKeyDetection · boolean · default: "false"

When true, the deterministicKeys rule also matches constructors annotated with @effect-identifier JSDoc tags, in addition to the standard structural detection.

Pipeable style

pipeableMinArgCount · number · default: "2"

Minimum number of contiguous pipeable transformation calls required to trigger the missedPipeableOpportunity diagnostic. Increase this value to reduce noise in codebases that prefer explicit style.

Layer graph and hover

mermaidProvider · string · default: "mermaid.live"

Mermaid rendering service used to generate Layer graph diagram links in hover output. Accepted values:

• "mermaid.live" — links open on mermaid.live
• "mermaid.com" — links open on mermaid.com
• Any custom URL — the diagram payload is appended to the provided base URL

noExternal · boolean · default: "false"

When true, external links (such as Mermaid diagram URLs) are suppressed from hover output. Useful in air-gapped environments or when external URL generation is undesirable.

layerGraphFollowDepth · number · default: "0"

How many levels deep the Layer graph extraction follows symbol references when building the hover diagram. 0 means only the immediate layer composition is shown. Higher values produce more complete graphs at the cost of analysis time.

Effect.fn quick fix variants

effectFn · string[] · default: "[\"span\"]"

Controls which effectFnOpportunity quick fix variants are offered when the diagnostic suggests wrapping a function with Effect.fn. Each entry is a variant name. The only built-in variant is "span".

"effectFn": ["span"]

Editor experience

inlays · boolean · default: "false"

When true, suppresses redundant return-type inlay hints on Effect.gen, Effect.fn, and Effect.fnUntraced generator functions where the return type is already clear from context.

Duplicate package detection

allowedDuplicatedPackages · string[] · default: "[]"

Package names that are permitted to appear in multiple versions without triggering the duplicatePackage diagnostic. Useful when a controlled multi-version scenario is intentional (e.g. migrating between major versions).

"allowedDuplicatedPackages": ["@effect/platform"]

Auto-import style

The four options below control how the language service suggests and organises imports. Package name matching is case-insensitive for all four options.

namespaceImportPackages · string[] · default: "[]"

Package names that should be imported as namespace imports (import * as X from '...') rather than named imports. Package matching is case-insensitive.

"namespaceImportPackages": ["effect", "@effect/platform"]

barrelImportPackages · string[] · default: "[]"

Package names that should use barrel named imports (import { X } from 'package') rather than deep-path imports. Package matching is case-insensitive.

"barrelImportPackages": ["lodash"]

importAliases · Record<string, string> · default: "{}"

Maps package names to preferred local import aliases. Keys are case-insensitive package name matches; values are the alias to use in generated imports.

"importAliases": {
  "effect": "Effect",
  "@effect/platform": "Platform"
}

topLevelNamedReexports · ignore | follow · default: "ignore"

Controls whether named re-exports at a package’s top-level entry point are followed when resolving import candidates. Accepted values are case-insensitive; invalid values fall back to "ignore".

• "ignore" — re-exports are not followed; only direct exports are considered.
• "follow" — re-exports are traversed to find the original export source.