effect-incremental-migration

Incremental Migration Skill

This skill provides a step-by-step template for converting existing async/Promise-based modules to Effect services. Preserve backward compatibility only where you still have non-Effect callers. The main goal is to move Effect callers onto yield* SomeService.Service early so dependency edges become explicit in the code and in the layer graph.

Effect Source Reference

The Effect v4 source is available at ~/.cache/effect-v4/. Browse and read files there directly to look up APIs, types, and implementations.

Reference this for:

• Context source: packages/effect/src/Context.ts
• Layer source: packages/effect/src/Layer.ts
• ManagedRuntime source: packages/effect/src/ManagedRuntime.ts
• Migration guide: MIGRATION.md
• Effect source: packages/effect/src/

The 7-Step Migration Template

Step 1: Define the Service Interface

Extract a named Interface type with Effect-returning methods. Keep parameter and return types identical to the original module — only swap Promise<T> for Effect.Effect<T, E>.

import type { Effect } from 'effect';

export namespace MyModule {
	export interface Interface {
		readonly get: (id: string) => Effect.Effect<Item, MyModuleError>;
		readonly list: Effect.Effect<ReadonlyArray<Item>>;
	}
}

Step 2: Declare the Service Class

Empty class body — no make:, no static readonly layer. The interface and service class live in the same namespace.

import { Context } from 'effect';
import type { Effect } from 'effect';

export namespace MyModule {
	export interface Interface {
		readonly get: (id: string) => Effect.Effect<Item, MyModuleError>;
		readonly list: Effect.Effect<ReadonlyArray<Item>>;
	}

	export class Service extends Context.Service<Service, Interface>()(
		'@app/MyModule'
	) {}
}

Step 3: Build the Raw Layer

Construct the service inside Layer.effect, capturing dependencies via yield*. Use Effect.fn for traced methods.

import { Effect, Layer, Context } from 'effect';

export namespace MyModule {
	export interface Interface {
		readonly get: (id: string) => Effect.Effect<Item, MyModuleError>;
		readonly list: Effect.Effect<ReadonlyArray<Item>>;
	}

	export class Service extends Context.Service<Service, Interface>()(
		'@app/MyModule'
	) {}

	export const layer = Layer.effect(
		Service,
		Effect.gen(function* () {
			const config = yield* Config.Service;
			const db = yield* Database.Service;

			const get = Effect.fn('MyModule.get')(function* (id: string) {
				const cfg = yield* config.get();
				return yield* db.findById(cfg.table, id);
			});

			const list = Effect.fn('MyModule.list')(function* () {
				const cfg = yield* config.get();
				return yield* db.listAll(cfg.table);
			});

			return Service.of({ get, list });
		})
	);
}