effect-platform-layers

Platform Layers

Master Effect platform layer provision for cross-platform applications. Use this skill when structuring applications that use Effect platform abstractions to ensure portability across Node.js and Bun environments.

The Golden Rule

Application code uses abstract interfaces. Platform-specific layers are provided either at the program entry point or inside a runtime-facing adapter module's defaultLayer.

// Application code - platform agnostic
import { Effect, FileSystem, Path, pipe } from 'effect';

const readConfig = Effect.gen(function* () {
	const fs = yield* FileSystem.FileSystem;
	const path = yield* Path.Path;
	const configPath = path.join('config', 'app.json');
	return yield* fs.readFileString(configPath);
});

// Entry point - platform specific
import { NodeServices, NodeRuntime } from '@effect/platform-node';

declare const program: Effect.Effect<void, never, never>;

pipe(program, Effect.provide(NodeServices.layer), NodeRuntime.runMain);

// WRONG - platform-specific imports in application code
import { readFileSync } from 'fs'; // Ties code to Node.js
import { FileSystem } from '@effect/platform-node'; // Platform-specific

Runtime-facing adapter modules may own their platform wiring directly:

export const defaultLayer = layer.pipe(
	Layer.provide(NodeFileSystem.layer),
	Layer.provide(NodePath.layer)
);

The important boundary is that downstream callers still depend on the abstract service, not on Node/Bun modules.

Platform Import Patterns

Node.js

import { NodeServices, NodeRuntime } from '@effect/platform-node';
import { Effect, pipe } from 'effect';

declare const program: Effect.Effect<void, never, never>;

pipe(program, Effect.provide(NodeServices.layer), NodeRuntime.runMain);

Bun

import { BunServices, BunRuntime } from '@effect/platform-bun';
import { Effect, pipe } from 'effect';

declare const program: Effect.Effect<void, never, never>;

pipe(program, Effect.provide(BunServices.layer), BunRuntime.runMain);