platform_skill

Overview

This skill explains @effect/platform, a platform-agnostic set of I/O abstractions for Effect programs. It covers HTTP client and server APIs, filesystem and key-value storage, terminal I/O, and worker/background capabilities across Node, Bun, and other runtimes. Use it to learn how to wire platform layers, validate inputs, and manage resources safely with Effect.

How this skill works

The skill describes Effect services (HttpClient, HttpServer, FileSystem, KeyValueStore, Terminal) as dependency-injected capabilities accessed inside Effect.gen or Effect effects. Concrete runtime implementations are provided via layers (for example NodeHttpClient.layer or NodeFileSystem.layer) so the same application code runs across environments. It also shows common patterns: making requests, handling responses, schema validation, file operations, and serving routes with request/body access.

When to use it

• You need to make HTTP requests or call external APIs from an Effect program.
• You are building an HTTP server using Effect's router and response builders.
• You want cross-platform file operations (read, write, stat, copy, remove) in Effect code.
• You need simple persistent storage via a KeyValueStore.
• You are implementing CLI input/output or background workers within Effect.

Best practices

• Always provide the appropriate platform layer for the runtime (Node/Bun) before running effects.
• Validate all external input and responses with Schema to avoid runtime shape errors.
• Scope resources (files, connections) with Effect.scoped or managed layers to ensure cleanup.
• Configure request timeouts and handle network/file errors explicitly.
• Keep server handlers pure effects and return HttpServerResponse builders for clarity.

Example use cases

• Call third-party REST APIs with HttpClient, parse JSON, and validate against a Schema.
• Build a REST API with HttpServer.router, route params, and schema-validated request bodies.
• Implement file-based configuration and content storage using FileSystem read/write/exists.
• Store user session or cache data in KeyValueStore with get/set/remove semantics.
• Create CLI tools that prompt users and display results using Terminal and NodeTerminal.layer.