Getting Started

These guides teach Effeck one topic at a time and also serve as a reference while you build. Start with Welcome, or jump to the subject you need.

Create and run your first project

bun create effeck my-app
cd my-app
bun run start
bun run test

With npm, run npm create effeck@latest my-app. The starter prints:

Hello, Effeck!
Recovered from EmptyName

src/greeting.effeck defines a greeting function and an EmptyName tagged error. src/main.effeck declares the abstract Greeter service, supplies its live layer, recovers a typed failure with try/catch, and exports main, which node dist/main.js runs with NodeRuntime.runMain. src/greeting.test.effeck uses it.effect to test success and recovery. Vitest compiles src/**/*.test.effeck through effeck-vite; tests need no prior build.

Run bun run dev to compile on changes and restart Node when output changes. Press Ctrl+C to stop both watchers. For diagnostics and hovers in VS Code or Cursor, install the extension that ships in effeck, then open the project:

code --install-extension node_modules/effeck/editor/effeck.vsix

See Installation for prerequisites, supported platforms, editor setup, and adding Effeck to an existing project.

Guides and reference material

function main() {
  const label = "first program"
  log(label)
  return label.length
}
// number!!

Read The Effect Type to understand this function's contract, Creating Effects to add failures, and Running Effects to execute it at an application boundary. Each guide explains a use case. The Effect 4 API reference lists library signatures, whose program arguments become zero-argument functions in Effeck.

Documentation versions

These pages target Effect 4.0.5 and the language decisions recorded with this repository. When opening upstream documentation, select version 4. Effect 3 examples use a different library version and do not establish which APIs are available here.

The upstream site also documents newer changes. Check a signature against your installed package when it differs from an example on these pages.

Finding a subject

The directories group guides by task:

• Error management: failures, recovery, retry, and timeouts.
• Concurrency: bounded parallel work and fiber lifetimes.
• Requirements: services and layers.
• Resources: acquisition and cleanup.
• Schema: decoding and validating external data.
• Observability: logs, metrics, spans, and fibers.
• Streams: incremental processing with backpressure.

Use each page's headings to find a specific operation. In a Markdown reader, follow the outline or search for an API name. The numbered file names preserve the learning sequence without requiring you to read every page in order.

Using documentation with language models

Provide the relevant Effeck guide alongside the Effect API signature. State that every function is an Effect, calls run, and a call passed where an operator expects a program is passed by name, as in fork(fetchReport()). Include your error and service declarations so generated code has enough information to preserve the contract.

Use compiler feedback and focused tests to check the result. Effect's TypeScript tooling applies to .ts integration code; the Devtools page explains Effeck's compiler, language server, linting, and debugging setup.

Upstream Effect page