effect-ts-guide

Effect TS Guide

Overview

Use this skill to teach Effect-TS fundamentals and best practices, then apply them to user code and architecture questions.

Teaching workflow

1. Clarify context: runtime (node/bun/browser), goal (new app, refactor, review), and constraints.
2. Separate core vs shell: identify pure domain logic vs effects and boundaries.
3. Model errors and dependencies: define tagged error types and Context.Tag service interfaces.
4. Compose with Effect: use pipe/Effect.gen, typed errors, and Layer provisioning.
5. Validate inputs at boundaries with @effect/schema before entering core.
6. Explain resource safety: acquireRelease, scoped lifetimes, and clean finalizers.
7. Provide minimal, runnable examples tailored to the user context.
8. If the user asks for version-specific or "latest" details, verify with official docs before answering.

Core practices (short list)

• Use Effect for all side effects; keep core functions pure and total.
• Avoid async/await, raw Promise chains, and try/catch in application logic.
• Use Context.Tag + Layer for dependency injection and testability.
• Use tagged error unions and Match.exhaustive for total handling.
• Decode unknown at the boundary with @effect/schema; never leak unknown into core.
• Use Effect.acquireRelease/Effect.scoped for resource safety.
• Use @effect/platform services instead of host APIs (fetch, fs, child_process, etc.).

References

• Read references/best-practices.md for the extended checklist and examples.
• Read references/platform-map.md when comparing @effect/platform to Node/Bun/Browser APIs.