DEV Community: Leonardo Marciano

Integrating Code Coverage with Codecov in Encore.ts

Leonardo Marciano — Tue, 04 Aug 2026 18:45:57 +0000

Track your test coverage and maintain code quality across deployments.

Introduction

In this tutorial, we'll integrate Codecov with your Encore.ts backend to automatically track test coverage on every push. The final setup gives you:

Coverage reports – Visual dashboards showing which lines are tested and which aren't.
Pull request comments – Automated coverage diffs showing impact of new changes.
GitHub badges – Display your coverage percentage directly in your README.

This is essential for teams that want to maintain high code quality standards and catch untested code before it reaches production.

Why Code Coverage Matters

Without coverage tracking, you're blind to:

Untested edge cases – Critical error paths that only fail in production.
Coverage regression – New features that reduce overall test coverage.
Team accountability – No visibility into who's writing tests and who isn't.

Coverage tracking creates a quality feedback loop:

Measure – Codecov analyzes your test suite execution.
Report – Coverage data appears in PRs and dashboards.
Improve – Team focuses on untested areas.
Maintain – Coverage gates prevent regression.

A well-monitored codebase stays healthy as it grows.

Getting Started

1. Install Encore & Create Your App

Install Encore CLI

# macOS
brew install encoredev/tap/encore

# Windows (PowerShell)
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

Create a new project

encore app create codecov-demo && cd codecov-demo
npm install --save-dev vitest @vitest/coverage-v8

2. Create a Codecov Account

Go to codecov.io and sign up with GitHub.
Add your repository (it will appear after your first push).
Copy your repository upload token from the settings page using Github Actions

3. Configure Your Test Setup

Update package.json

Add the test scripts to your package.json to enable coverage tracking:

{
  "scripts": {
    "test": "vitest run --coverage",
    "test:coverage": "encore test"
  }
}

Script explanations:

test - Runs Vitest with coverage reporting (for local development and CI)
test:coverage - Uses Encore's built-in test runner which handles the Encore environment properly

Why two scripts? The test script is perfect for CI/CD pipelines, while test:coverage leverages Encore's test runner which automatically handles service dependencies and environment setup.

Create vitest.config.ts

import path from 'node:path';
/// <reference types="vitest" />
import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    alias: {
      '~encore': path.resolve(__dirname, './encore.gen'),
    },
  },
  test: {
    coverage: {
      exclude: ['encore.gen/**', 'node_modules/**', '**/*.service.ts', '**/encore.service.ts'],
      include: ['apps/**'],
    },
  },
});

Update .gitignore

Add coverage files to your .gitignore to avoid committing generated coverage reports:

.encore
encore.gen.go
encore.gen.cue
/.encore
node_modules
/encore.gen

# Coverage reports
coverage
.DS_Store

Important: Coverage reports are generated locally and in CI, but should never be committed to your repository. Codecov will handle the coverage data through its API.

Backend Implementation

Let's create a simple service with tests to demonstrate coverage tracking.

Note: We're using the apps/ directory structure to match our codecov.yml configuration, which only tracks files within this directory. You can adjust the paths in codecov.yml if you prefer a different structure like services/.

1. Create a Math Service

apps/math/encore.service.ts

import { Service } from "encore.dev/service";

export default new Service("math");

2. Add Business Logic

apps/math/calculator.ts

/**
 * Calculator module with basic math operations
 * This demonstrates code that needs test coverage
 */

export class Calculator {
  /**
   * Add two numbers together
   */
  add(a: number, b: number): number {
    return a + b;
  }

  /**
   * Subtract b from a
   */
  subtract(a: number, b: number): number {
    return a - b;
  }

  /**
   * Multiply two numbers
   */
  multiply(a: number, b: number): number {
    return a * b;
  }

  /**
   * Divide a by b with error handling
   */
  divide(a: number, b: number): number {
    if (b === 0) {
      throw new Error("Division by zero is not allowed");
    }
    return a / b;
  }

  /**
   * Calculate percentage
   */
  percentage(value: number, total: number): number {
    if (total === 0) {
      return 0;
    }
    return (value / total) * 100;
  }
}

3. Create API Endpoints

apps/math/api.ts

import { api } from "encore.dev/api";
import { Calculator } from "./calculator";

const calc = new Calculator();

interface MathOperation {
  a: number;
  b: number;
}

interface MathResult {
  result: number;
}

/**
 * Add two numbers
 */
export const add = api(
  { method: "POST", path: "/math/add", expose: true },
  async ({ a, b }: MathOperation): Promise<MathResult> => {
    const result = calc.add(a, b);
    return { result };
  }
);

/**
 * Subtract two numbers
 */
export const subtract = api(
  { method: "POST", path: "/math/subtract", expose: true },
  async ({ a, b }: MathOperation): Promise<MathResult> => {
    const result = calc.subtract(a, b);
    return { result };
  }
);

/**
 * Multiply two numbers
 */
export const multiply = api(
  { method: "POST", path: "/math/multiply", expose: true },
  async ({ a, b }: MathOperation): Promise<MathResult> => {
    const result = calc.multiply(a, b);
    return { result };
  }
);

/**
 * Divide two numbers
 */
export const divide = api(
  { method: "POST", path: "/math/divide", expose: true },
  async ({ a, b }: MathOperation): Promise<MathResult> => {
    const result = calc.divide(a, b);
    return { result };
  }
);

4. Write Unit Tests

apps/math/calculator.test.ts

import { describe, it, expect } from 'vitest';
import { Calculator } from './calculator';

describe('Calculator', () => {
  const calc = new Calculator();

  describe('add', () => {
    it('should add two positive numbers', () => {
      expect(calc.add(2, 3)).toBe(5);
    });

    it('should handle negative numbers', () => {
      expect(calc.add(-1, -1)).toBe(-2);
    });
  });

  describe('subtract', () => {
    it('should subtract two numbers', () => {
      expect(calc.subtract(5, 3)).toBe(2);
    });
  });

  describe('multiply', () => {
    it('should multiply two numbers', () => {
      expect(calc.multiply(4, 5)).toBe(20);
    });
  });

  describe('divide', () => {
    it('should divide two numbers', () => {
      expect(calc.divide(10, 2)).toBe(5);
    });

    it('should throw error for division by zero', () => {
      expect(() => calc.divide(10, 0)).toThrow('Division by zero is not allowed');
    });
  });

  // Note: We're intentionally not testing percentage() to demonstrate uncovered code
});

5. Configure GitHub Actions

Create .github/workflows/codecov.yml:

name: Run tests and upload coverage

on:
  push:

jobs:
  test:
    name: Run tests and collect coverage
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Set up Docker
        uses: docker/setup-buildx-action@v3

      - name: Install dependencies
        run: npm install

      - name: Install Encore CLI
        run: |
          curl -L https://encore.dev/install.sh | bash
          echo "${HOME}/.encore/bin" >> $GITHUB_PATH

      - name: Authenticate with Encore
        run: encore auth login --auth-key=${{ secrets.ENCORE_AUTH }}
        env:
          ENCORE_AUTH: ${{ secrets.ENCORE_AUTH }}

      - name: Run tests
        run: npm run test:coverage

      - name: Upload results to Codecov
        uses: codecov/codecov-action@v5
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          directory: ./coverage/
          flags: typescript,backend
          fail_ci_if_error: false
          verbose: true
          name: encore-example-coverage
          working-directory: ${{ github.workspace }}
          root_dir: ${{ github.workspace }}

Setting Up GitHub Secrets

1. Get Your Encore Auth Key

Open your Encore dashboard at app.encore.dev.
Navigate to Settings → Auth Tokens.
Click Create New Token and name it "GitHub Actions".
Copy the generated token.

2. Get Your Codecov Token

Go to your repository settings in Codecov.
Find the Upload Token section.
Copy the repository token.

3. Add Secrets to GitHub

Go to your GitHub repository.
Navigate to Settings → Secrets and variables → Actions.
Click New repository secret.
Add two secrets:
- Name: ENCORE_AUTH, Value: Your Encore auth token
- Name: CODECOV_TOKEN, Value: Your Codecov upload token

Running the Application

Run tests locally

   npm run test:coverage

You can also use the standard test script for CI-style testing:

   npm run test

You'll see output like:

 ✓ apps/math/calculator.test.ts (6 tests) 6ms
   ✓ Calculator > add > should add two positive numbers 2ms
   ✓ Calculator > add > should handle negative numbers 0ms
   ✓ Calculator > subtract > should subtract two numbers 0ms
   ✓ Calculator > multiply > should multiply two numbers 0ms
   ✓ Calculator > divide > should divide two numbers 0ms
   ✓ Calculator > divide > should throw error for division by zero 1ms

 Test Files  1 passed (1)
      Tests  6 passed (6)
   Start at  15:11:50
   Duration  524ms (transform 57ms, setup 0ms, collect 40ms, tests 6ms, environment 0ms, prepare 202ms)

 % Coverage report from v8
---------------|---------|----------|---------|---------|-------------------
File           | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
---------------|---------|----------|---------|---------|-------------------
All files      |   33.33 |    83.33 |   66.66 |   33.33 |                  
 api.ts        |       0 |        0 |       0 |       0 | 1-57             
 calculator.ts |   78.26 |      100 |      80 |   78.26 | 42-46            
---------------|---------|----------|---------|---------|-------------------

Push to GitHub

   git add .
   git commit -m "Add calculator with tests"
   git push origin main

Check GitHub Actions

Go to the Actions tab in your repository to see the workflow running.

View Coverage Report

Once complete, check Codecov for your coverage report.

Adding Coverage Badge

Make your coverage visible in your README:

README.md

# My Encore App

[![codecov](https://codecov.io/gh/YOUR_USERNAME/YOUR_REPO/branch/main/graph/badge.svg)](https://codecov.io/gh/YOUR_USERNAME/YOUR_REPO)

This is my Encore backend with automated test coverage tracking.

Deployment

1. Push!

git remote add origin https://your-repo-url.com/repo
git push encore main

2. Coverage in Pull Requests

When you create pull requests, Codecov will automatically:

Comment with coverage changes
Show which lines are covered/uncovered
Fail checks if coverage drops below threshold

3. Set Coverage Requirements (Optional)

Create codecov.yml in your repository root:

codecov:
  require_ci_to_pass: false # Set to false during troubleshooting
  notify:
    wait_for_ci: true
  branch: main

coverage:
  precision: 2
  round: down
  range: "70...100"
  status:
    project:
      default: # Overall project coverage
        target: 100%
        threshold: 1%
        informational: false
        if_ci_failed: error # fail the status if CI fails
        only_pulls: false # post status on commits and PRs
        paths:
          - "apps/"  # only include apps directory
        flag_coverage_not_uploaded_behavior: include
      # You can add additional project status checks for specific components
      # frontend:
      #   flags:
      #     - frontend
      #   target: 90%
      backend:
        flags:
          - backend
        target: 95%

    patch: # Coverage of the PR diff
      default:
        target: 100% # require 100% coverage for new/modified code
        threshold: 0% # no threshold allowed for patch
        base: auto # compare against parent commit
        informational: false # block PRs if patch coverage is insufficient
        only_pulls: true # only check patch coverage on PRs

    # Report changes in coverage not directly modified in the PR
    changes: true # enable unexpected coverage change detection

# Define flags for TypeScript codebase
flags:
  typescript:
    paths:
      - apps/.*\.ts$
      - apps/.*\.tsx$
    carryforward: true
    # Only include TypeScript files within the apps directory

ignore:
  - "encore.gen/"  # Ignore generated code

comment:
  # Ensure comments are posted on PRs
  layout: "header, diff, flags, files, footer"
  behavior: new  # Delete old comment and post new one
  require_changes: false  # Post comment even if there are no coverage changes
  require_base: false  # Don't require base report to post comment
  require_head: true  # Require head report to post comment
  hide_project_coverage: false  # Show both project and patch coverage

Understanding the Configuration

This comprehensive setup provides:

Coverage Standards:

Project target: 100% overall coverage with 1% threshold
Backend target: 95% for backend-specific code
Patch target: 100% for all new/modified code
Range: Visual indicators from 70% (red) to 100% (green)

Smart Filtering:

Only tracks TypeScript files in the apps/ directory
Ignores Encore's generated code (encore.gen/)
Separate flags for backend tracking

PR Integration:

Comments on every PR with coverage details
Shows file-by-file breakdown
Blocks PRs if new code isn't 100% covered
Detects unexpected coverage changes

Error Handling:

Continues even if CI has issues (for troubleshooting)
Fails status checks if CI completely fails
Includes coverage even if flags aren't uploaded

Next Steps

Integration tests – Test your API endpoints with supertest
E2E tests – Add Playwright for full user flow testing
Branch coverage – Ensure all conditional paths are tested
Coverage gates – Block merges that reduce coverage
Team dashboards – Create coverage leaderboards
Historical tracking – Monitor coverage trends over time

Congratulations!

You now have automated code coverage tracking that helps maintain quality as your Encore backend grows. Every push is analyzed, every PR shows impact, and your team stays accountable for test coverage.

Encore.ts + Effect.ts : Building a Production-Ready Task Management System with Functional TypeScript

Leonardo Marciano — Thu, 12 Mar 2026 03:04:16 +0000

Introduction

What if your backend could have typed errors that compile down to HTTP status codes, automatic request batching, fiber-based concurrency with semaphores and queues, and auto-provisioned databases, PubSub, and object storage... all in TypeScript?

That's what happens when you combine Effect.ts and Encore.ts.

Effect.ts gives you a functional programming toolkit for TypeScript: composable effects, typed errors, dependency injection via layers, streams, concurrency primitives (fibers, semaphores, queues), and a schema system that makes Zod look like a toy.

Encore.ts gives you infrastructure-as-code: declare a SQLDatabase, Topic, Bucket, or CronJob in your TypeScript code, and Encore provisions it automatically. Locally, in preview environments, and in production. No Terraform(Must read: The Last Year of Terraform), no Docker Compose, no YAML.

Together, they're remarkably complementary. Effect handles the how (composition, error handling, concurrency), Encore handles the what (databases, messaging, auth, deployment).

In this article, I'll walk you through a Task Management System (think mini Jira/Linear) we built with 7 microservices, covering virtually every major feature of both frameworks. This isn't a toy example. It's a reference architecture you can study, fork, and build on.

System Architecture

Here's the bird's-eye view of our system:

Client Request
    │
    ▼
┌─────────┐     ┌──────┐
│ Gateway │────▶│ auth │ validates JWT token
└────┬────┘     └──────┘
     │
     ▼
┌────────────┐
│ Middleware │ enriches request (timing/tracing)
└─────┬──────┘
      │
      ├──▶ [user]          ◀── service-to-service ── [project], [auth]
      │      ├── users DB
      │      └── Effect Cache (permissions)
      │
      ├──▶ [project]
      │      └── projects DB + project_members
      │
      ├──▶ [task]          ──▶ publishes to PubSub topics
      │      ├── tasks DB + comments
      │      ├── CronJob (stale task check)
      │      └── WebSocket streams (activity feed)
      │
      ├──▶ [notification]  ◀── subscribes to PubSub topics
      │      ├── notifications DB
      │      ├── Queue + Deferred (async dispatch)
      │      └── WebSocket stream (real-time push)
      │
      ├──▶ [analytics]     ◀── subscribes to PubSub topics
      │      ├── analytics DB (events + daily_stats)
      │      ├── Encore Metrics (Counter, Gauge)
      │      └── Effect Stream/Sink (aggregation pipelines)
      │
      └──▶ [storage]
             ├── Encore Bucket (object storage)
             └── Effect Semaphore (rate limiting)

Each service has its own encore.service.ts, its own database (auto-provisioned by Encore), and communicates via PubSub topics for async events or direct service-to-service calls for synchronous operations.

The Bridge: Connecting Effect.ts to Encore.ts

This is the single most important pattern in the entire codebase. Encore expects your API handlers to be async functions that return Promises. Effect programs return Effect<A, E> values. We need a bridge.

Here's runEffect. Every Encore endpoint calls this:

import { Cause, Chunk, Effect, Exit, Match, pipe } from "effect"
import { APIError } from "encore.dev/api"
import type { AppError } from "./errors.js"

export const runEffect = async <A, E extends AppError>(
  effect: Effect.Effect<A, E>,
): Promise<A> => {
  const exit = await Effect.runPromiseExit(
    effect.pipe(
      Effect.withSpan("encore-handler"),
      Effect.annotateLogs("runtime", "encore"),
    ),
  )

  if (Exit.isSuccess(exit)) {
    return exit.value
  }

  const cause = exit.cause

  // Expected errors → translate to APIError
  if (Cause.isFailType(cause)) {
    throw effectErrorToAPIError(cause.error as AppError)
  }

  // Fiber interruption → aborted
  if (Cause.isInterruptType(cause)) {
    throw APIError.aborted("Request was interrupted")
  }

  // Defects (bugs) → internal error
  if (Cause.isDieType(cause)) {
    console.error("Unexpected defect:", cause.defect)
    throw APIError.internal("Internal server error")
  }

  // Composite causes → extract first failure
  const failures = Chunk.toArray(Cause.failures(cause))
  if (failures.length > 0) {
    throw effectErrorToAPIError(failures[0] as AppError)
  }

  throw APIError.internal("Unknown error")
}

The key insight: Effect's Exit type distinguishes between expected failures (your domain errors), defects (bugs/panics), and interruptions (cancelled fibers). We handle each differently.

The error translation uses Effect's Match module for exhaustive mapping:

export const effectErrorToAPIError = (error: AppError): APIError =>
  pipe(
    error,
    Match.value,
    Match.tag("NotFoundError", (e) =>
      APIError.notFound(`${e.entity} '${e.id}' not found`)),
    Match.tag("ValidationError", (e) =>
      APIError.invalidArgument(`${e.field}: ${e.message}`)),
    Match.tag("AuthenticationError", (e) =>
      APIError.unauthenticated(e.reason)),
    Match.tag("AuthorizationError", (e) =>
      APIError.permissionDenied(
        `User '${e.userId}' cannot '${e.action}' on '${e.resource}'`)),
    Match.tag("RateLimitError", (e) =>
      APIError.resourceExhausted(`Rate limited. Retry after ${e.retryAfter}s`)),
    Match.tag("DatabaseError", (e) =>
      APIError.internal(`Database error in '${e.operation}'`)),
    Match.tag("InvalidStateTransitionError", (e) =>
      APIError.failedPrecondition(
        `Cannot transition ${e.entity} from '${e.from}' to '${e.to}'`)),
    // ... all 10 error types mapped
    Match.exhaustive, // Compiler error if you miss one!
  )

Match.exhaustive is the magic. If you add a new error type to AppError but forget to handle it here, TypeScript won't compile. No more silent 500s from unhandled error cases.

And this is how every Encore endpoint looks:

import { api } from "encore.dev/api"
import { Effect } from "effect"
import { TaskService, TaskServiceLive } from "./task-service.js"
import { runEffect } from "../shared/effect-encore-bridge.js"

export const getTask = api(
  { expose: true, method: "GET", path: "/tasks/:id", auth: true },
  async ({ id }: { id: string }): Promise<TaskResponse> =>
    runEffect(
      Effect.gen(function* () {
        const service = yield* TaskService
        return yield* service.getById(TaskId(id))
      }).pipe(Effect.provide(TaskServiceLive))
    )
)

Clean, consistent, and every error is automatically translated to the correct HTTP status code.

Type Safety with Branded Types

A UserId is a string. A ProjectId is also a string. But they are not the same thing. Effect's Brand module prevents you from accidentally passing one where the other is expected:

import { Brand, Order, Equivalence, Equal, Hash } from "effect"

export type UserId = string & Brand.Brand<"UserId">
export const UserId = Brand.nominal<UserId>()

export type ProjectId = string & Brand.Brand<"ProjectId">
export const ProjectId = Brand.nominal<ProjectId>()

export type TaskId = string & Brand.Brand<"TaskId">
export const TaskId = Brand.nominal<TaskId>()

Now service.getById(TaskId("abc")) compiles, but service.getById(UserId("abc")) is a type error. This catches entire classes of bugs at compile time. Imagine an accidental WHERE user_id = $projectId query that silently returns nothing.

We also get custom ordering for sorting:

export type TaskPriority = "critical" | "high" | "medium" | "low"

const priorityRank: Record<TaskPriority, number> = {
  critical: 0, high: 1, medium: 2, low: 3,
}

export const TaskPriorityOrder: Order.Order<TaskPriority> =
  Order.mapInput(Order.number, (p: TaskPriority) => priorityRank[p])

And custom Equal + Hash implementations for use in HashMap/HashSet:

export class ProjectMemberKey implements Equal.Equal {
  constructor(readonly projectId: ProjectId, readonly userId: UserId) {}

  [Equal.symbol](that: Equal.Equal): boolean {
    if (that instanceof ProjectMemberKey) {
      return this.projectId === that.projectId && this.userId === that.userId
    }
    return false
  }

  [Hash.symbol](): number {
    return Hash.combine(Hash.hash(this.projectId))(Hash.hash(this.userId))
  }
}

Typed Error Hierarchy

Every error in the system extends Data.TaggedError, making them yieldable inside Effect.gen generators:

import { Data } from "effect"

export class NotFoundError extends Data.TaggedError("NotFoundError")<{
  readonly entity: string
  readonly id: string
}> {}

export class ValidationError extends Data.TaggedError("ValidationError")<{
  readonly field: string
  readonly message: string
}> {}

export class InvalidStateTransitionError extends Data.TaggedError(
  "InvalidStateTransitionError"
)<{
  readonly entity: string
  readonly from: string
  readonly to: string
}> {}

// ... 10 total error types

export type AppError =
  | DatabaseError | NotFoundError | ValidationError
  | AuthenticationError | AuthorizationError | ConflictError
  | RateLimitError | ExternalServiceError | TimeoutError
  | InvalidStateTransitionError

The discriminated union AppError is what makes Match.exhaustive work in the bridge. Each error carries structured context (not just a message string), so the API response can be precise:

TaggedError	HTTP Status	Example Message
`NotFoundError`	404	`Task 'abc-123' not found`
`ValidationError`	400	`title: Must be at least 1 character`
`AuthenticationError`	401	`Invalid or expired token`
`AuthorizationError`	403	`User 'u1' cannot 'delete' on 'Project'`
`ConflictError`	409	`User: Email already exists`
`RateLimitError`	429	`Rate limited. Retry after 30s`
`InvalidStateTransitionError`	400	`Cannot transition Task from 'done' to 'in_progress'`
`DatabaseError`	500	`Database error in 'queryRow'`
`ExternalServiceError`	503	`Service 'object-storage' unavailable`
`TimeoutError`	504	`'queryRow' timed out after 5000ms`

Schema: Bidirectional Validation

Effect Schema handles two things that Encore's built-in validation doesn't: domain object validation and database row transformation.

Encore validates at the HTTP boundary (email format, string length). Effect Schema validates at the domain boundary and transforms between database rows (snake_case) and domain objects (camelCase):

import { Schema } from "effect"

export class TaskSchema extends Schema.Class<TaskSchema>("TaskSchema")({
  id: Schema.String.pipe(Schema.brand("TaskId")),
  title: Schema.String.pipe(
    Schema.minLength(1), Schema.maxLength(200),
    Schema.annotations({ description: "Task title" })
  ),
  status: Schema.optionalWith(TaskStatusSchema, {
    default: () => "backlog" as const
  }),
  priority: Schema.optionalWith(TaskPrioritySchema, {
    default: () => "medium" as const
  }),
  storyPoints: Schema.OptionFromNullOr(
    Schema.Number.pipe(Schema.int(), Schema.between(1, 21))
  ),
  // ...
}) {}

The bidirectional transform between DB rows and domain objects:

export const TaskFromRow = Schema.transform(
  // From: database row (snake_case)
  Schema.Struct({
    id: Schema.String,
    title: Schema.String,
    assignee_id: Schema.NullOr(Schema.String),
    project_id: Schema.String,
    created_at: Schema.String,
    // ...
  }),
  // To: domain object (camelCase + branded)
  Schema.Struct({
    id: Schema.String.pipe(Schema.brand("TaskId")),
    title: Schema.String,
    assigneeId: Schema.NullOr(Schema.String.pipe(Schema.brand("UserId"))),
    projectId: Schema.String.pipe(Schema.brand("ProjectId")),
    createdAt: Schema.String,
    // ...
  }),
  {
    strict: true,
    decode: (row) => ({
      id: row.id as any,
      title: row.title,
      assigneeId: row.assignee_id as any,
      projectId: row.project_id as any,
      createdAt: row.created_at,
    }),
    encode: (task) => ({
      id: task.id,
      title: task.title,
      assignee_id: task.assigneeId,
      project_id: task.projectId,
      created_at: task.createdAt,
    }),
  }
)

Passwords use Schema.Redacted so they never appear in logs:

export const PasswordHashSchema = Schema.Redacted(Schema.String)

Resilience: Retry, Timeout, Schedule

Every database query in the system goes through a retry + timeout wrapper:

import { Effect, Schedule, Duration, pipe, Option, Chunk } from "effect"

// Exponential backoff (100ms, 200ms, 400ms) + jitter + max 3 retries
export const dbRetrySchedule = Schedule.exponential("100 millis").pipe(
  Schedule.intersect(Schedule.recurs(3)),
  Schedule.jittered
)

export const queryRowEffect = <T>(
  db: SQLDatabase,
  queryFn: () => Promise<T | null>
): Effect.Effect<Option.Option<T>, DatabaseError> =>
  pipe(
    Effect.tryPromise({
      try: () => queryFn(),
      catch: (e) => new DatabaseError({ operation: "queryRow", cause: e }),
    }),
    Effect.map(Option.fromNullable),
    Effect.retry(dbRetrySchedule),
    Effect.timeout(Duration.seconds(5)),
    Effect.catchTag("TimeoutException", () =>
      Effect.fail(new DatabaseError({
        operation: "queryRow",
        cause: "Query timed out after 5s"
      }))
    )
  )

Schedule.intersect combines two schedules: "exponential backoff" AND "max 3 attempts". Schedule.jittered adds randomness to prevent thundering herd problems when multiple requests retry simultaneously.

The task scheduler demonstrates more advanced Schedule combinators:

import { CronJob } from "encore.dev/cron"
import { Schedule } from "effect"

// Encore CronJob triggers the endpoint every hour
const _ = new CronJob("stale-task-check", {
  title: "Check for stale tasks",
  every: "1h",
  endpoint: checkStaleTasks,
})

// Effect Schedule for retry within the job
const staleCheckSchedule = Schedule.exponential("1 second").pipe(
  Schedule.jittered,
  Schedule.intersect(Schedule.recurs(3)),
  Schedule.union(Schedule.spaced(Duration.seconds(30))),
)

State Machine with Match

Task status transitions follow strict rules. You can't go from backlog directly to done. The state machine is implemented with Effect's Match module:

import { Data, Match } from "effect"

class StateTransition extends Data.Class<{
  readonly from: string
  readonly to: string
}> {}

const isValidTransition = (from: string, to: string): boolean =>
  Match.value(new StateTransition({ from, to })).pipe(
    Match.when({ from: "backlog", to: "todo" }, () => true),
    Match.when({ from: "todo", to: "in_progress" }, () => true),
    Match.when({ from: "todo", to: "cancelled" }, () => true),
    Match.when({ from: "in_progress", to: "in_review" }, () => true),
    Match.when({ from: "in_progress", to: "todo" }, () => true),
    Match.when({ from: "in_review", to: "done" }, () => true),
    Match.when({ from: "in_review", to: "in_progress" }, () => true),
    Match.when({ from: "done", to: "todo" }, () => true), // reopen
    Match.orElse(() => false),
  )

Used in the transition method:

transition: (id, newStatus) =>
  Effect.gen(function* () {
    const task = yield* repo.findById(id)
    const fromStatus = task.status

    if (!isValidTransition(fromStatus, newStatus)) {
      return yield* Effect.fail(
        new InvalidStateTransitionError({
          entity: "Task", from: fromStatus, to: newStatus,
        })
      )
    }

    const updated = yield* repo.update(id, { status: newStatus })
    return { task: updated, fromStatus }
  }).pipe(Effect.withSpan("TaskService.transition")),

Bulk updates use error accumulation. Each update is independent, and failures don't block successes:

bulkUpdateStatus: (updates) =>
  Effect.forEach(
    updates,
    (u) =>
      pipe(
        Effect.gen(function* () {
          const task = yield* repo.findById(u.id)
          if (!isValidTransition(task.status, u.status)) {
            return yield* Effect.fail(
              new InvalidStateTransitionError({
                entity: "Task", from: task.status, to: u.status,
              })
            )
          }
          return yield* repo.update(u.id, { status: u.status })
        }),
        Effect.either, // Convert to Either: Right(task) | Left(error)
      ),
    { concurrency: 5 }, // Process 5 at a time
  ),

The API returns { succeeded: Task[], failed: { id, error }[] } so the caller sees exactly what worked and what didn't.

Concurrency and Rate Limiting

Semaphore: Controlling Upload Concurrency

The storage service limits concurrent uploads to 10 using an Effect Semaphore:

import { Effect, Duration, pipe } from "effect"

export const makeUploadLimiter = Effect.gen(function* () {
  const semaphore = yield* Effect.makeSemaphore(10)

  return {
    withLimit: <A, E>(
      effect: Effect.Effect<A, E>
    ): Effect.Effect<A, E | RateLimitError> =>
      pipe(
        semaphore.withPermits(1)(effect),
        Effect.timeout(Duration.seconds(30)),
        Effect.catchTag("TimeoutException", () =>
          Effect.fail(new RateLimitError({ retryAfter: 30 }))
        )
      ),
  }
})

If all 10 permits are taken, the 11th upload waits. If it waits more than 30 seconds, it gets a 429 Too Many Requests response.

Queue + Deferred: Async Notification Dispatch

The notification service uses a bounded queue with completion signaling:

import { Deferred, Effect, Fiber, Queue } from "effect"

export const makeNotificationDispatcher = Effect.gen(function* () {
  const queue = yield* Queue.bounded<PendingNotification>(1000)
  const startGate = yield* Deferred.make<void>()

  // Background consumer fiber
  const consumer = yield* Effect.fork(
    Effect.gen(function* () {
      yield* Deferred.await(startGate) // Wait until ready

      yield* Effect.forever(
        Effect.gen(function* () {
          const notification = yield* Queue.take(queue)
          const result = yield* pipe(
            Effect.logInfo(`Dispatching to ${notification.userId}`),
            Effect.either,
          )
          // Signal completion back to the producer
          if (result._tag === "Right") {
            yield* Deferred.succeed(notification.completion, undefined)
          } else {
            yield* Deferred.fail(notification.completion, /* error */)
          }
        }),
      )
    }),
  )

  return {
    enqueue: (input) =>
      Effect.gen(function* () {
        const deferred = yield* Deferred.make<void, ExternalServiceError>()
        yield* Queue.offer(queue, { ...input, completion: deferred })
        return yield* Deferred.await(deferred) // Wait for processing
      }),
    start: Deferred.succeed(startGate, undefined),
    shutdown: pipe(Queue.shutdown(queue), Effect.flatMap(() => Fiber.interrupt(consumer))),
  }
})

Three primitives working together:

Queue.bounded(1000): Backpressure. If 1000 notifications are pending, producers wait.
Deferred: One-shot promise. Each notification gets a completion signal.
Fiber: Background consumer runs independently, interrupted on shutdown.

Automatic Batching with RequestResolver

When you need to load 50 tasks in a list view, you don't want 50 separate SQL queries. Effect's RequestResolver automatically batches them:

import { Effect, Request, RequestResolver } from "effect"

interface GetTaskById extends Request.Request<Task, NotFoundError> {
  readonly _tag: "GetTaskById"
  readonly id: TaskId
}

const GetTaskById = Request.tagged<GetTaskById>("GetTaskById")

const TaskBatchResolver = RequestResolver.makeBatched(
  (requests: ReadonlyArray<GetTaskById>) =>
    Effect.gen(function* () {
      const repo = yield* TaskRepo
      const ids = requests.map((r) => r.id)
      // ONE query instead of N
      const tasks = yield* repo.findByIds(ids)
      const taskMap = new Map(tasks.map((t) => [t.id, t]))

      for (const req of requests) {
        const task = taskMap.get(req.id)
        if (task) yield* Request.succeed(req, task)
        else yield* Request.fail(req,
          new NotFoundError({ entity: "Task", id: req.id }))
      }
    }),
)

// Usage: these calls are automatically batched!
export const getTasksBatched = (ids: TaskId[]) =>
  Effect.forEach(ids, (id) =>
    Effect.request(GetTaskById({ id }), TaskBatchResolver),
    { concurrency: "unbounded", batching: true }
  )

Call getTasksBatched(["a", "b", "c", ..., "z"]) and Effect will execute one SELECT ... WHERE id IN (...) query instead of 26 individual queries. The batching is transparent to the caller.

Reactive State: Ref, SynchronizedRef, SubscriptionRef

The task board maintains real-time state using three flavors of mutable references:

import {
  Data, Effect, HashMap, HashSet,
  Ref, SubscriptionRef, SynchronizedRef
} from "effect"

export class BoardState extends Data.Class<{
  readonly tasksByStatus: HashMap.HashMap<string, HashSet.HashSet<string>>
  readonly activeViewers: HashSet.HashSet<string>
  readonly lastUpdated: number
}> {}

export const makeBoardState = Effect.gen(function* () {
  // SynchronizedRef: atomic effectful updates
  const boardRef = yield* SynchronizedRef.make(
    new BoardState({
      tasksByStatus: HashMap.empty(),
      activeViewers: HashSet.empty(),
      lastUpdated: Date.now(),
    }),
  )

  // SubscriptionRef: observable — clients subscribe to changes
  const activityRef = yield* SubscriptionRef.make<ActivityEvent>(/* initial */)

  // Ref: simple counter
  const opsCounterRef = yield* Ref.make(0)

  return {
    moveTask: (taskId, fromStatus, toStatus) =>
      pipe(
        SynchronizedRef.updateEffect(boardRef, (state) =>
          Effect.gen(function* () {
            const fromSet = HashMap.get(state.tasksByStatus, fromStatus)
              .pipe(opt => opt._tag === "Some" ? opt.value : HashSet.empty())
            const toSet = HashMap.get(state.tasksByStatus, toStatus)
              .pipe(opt => opt._tag === "Some" ? opt.value : HashSet.empty())
            return new BoardState({
              tasksByStatus: pipe(
                state.tasksByStatus,
                HashMap.set(fromStatus, HashSet.remove(fromSet, taskId)),
                HashMap.set(toStatus, HashSet.add(toSet, taskId)),
              ),
              activeViewers: state.activeViewers,
              lastUpdated: Date.now(),
            })
          }),
        ),
        Effect.tap(() => Ref.update(opsCounterRef, (n) => n + 1)),
      ),

    // Stream of changes for WebSocket push
    activityStream: activityRef.changes,
  }
})

Ref: Simple mutable value (like useState but for Effect).
SynchronizedRef: Effectful atomic updates. The update function can do async work.
SubscriptionRef: Like SynchronizedRef, but consumers can subscribe to .changes, which exposes a Stream of every update.

Streams and Sinks for Data Processing

The analytics service processes events through Stream pipelines and collects results with Sinks:

import { Chunk, Stream, Schedule, Duration, Effect, pipe } from "effect"

export const aggregateEventsStream = (
  events: Stream.Stream<AnalyticsEvent>,
) =>
  pipe(
    events,
    Stream.grouped(100),          // Batch into chunks of 100
    Stream.map((chunk) => {       // Aggregate each batch
      const byProject = new Map<string, { created: number; completed: number }>()
      for (const event of chunk) {
        const projectId = event.metadata.projectId ?? "unknown"
        const current = byProject.get(projectId) ?? { created: 0, completed: 0 }
        if (event.eventType === "task_created") current.created++
        byProject.set(projectId, current)
      }
      return Array.from(byProject.entries()).map(([projectId, stats]) => ({
        projectId, ...stats,
      }))
    }),
    Stream.mapConcat((arr) => arr), // Flatten arrays
  )

// Running totals with stateful transformation
export const runningTotalsStream = (events: Stream.Stream<AnalyticsEvent>) =>
  Stream.mapAccum(events, 0, (total, event) => {
    const newTotal = total + 1
    return [newTotal, { total: newTotal, eventType: event.eventType }]
  })

Sinks consume streams and produce final results:

import { Sink, Effect, pipe } from "effect"

// Count all events
export const countEventsSink = Sink.foldLeft(
  0, (count, _event: AnalyticsEvent) => count + 1
)

// Aggregate by type
export const aggregateByTypeSink = Sink.foldLeft(
  new Map<string, number>(),
  (acc, event: AnalyticsEvent) => {
    acc.set(event.eventType, (acc.get(event.eventType) ?? 0) + 1)
    return acc
  }
)

// Compose: count then log
export const countAndLogSink = pipe(
  countEventsSink,
  Sink.zipRight(Sink.fromEffect(Effect.logInfo("Finished counting events"))),
)

Metrics at Two Levels

We track metrics at two levels. Encore metrics get exported to your cloud provider's monitoring. Effect metrics handle internal runtime observability:

import { Effect, Metric, MetricBoundaries, pipe } from "effect"
import { Counter, Gauge } from "encore.dev/metrics"

// Encore: infrastructure-level metrics
export const tasksCreatedTotal = new Counter("tasks_created_total")
export const activeUsersGauge = new Gauge("active_users")

// Effect: runtime-level metrics
export const taskProcessingDuration = Metric.histogram(
  "effect_task_processing_duration_ms",
  MetricBoundaries.linear({ start: 0, width: 100, count: 10 }),
)

// Helper: measure any effect's duration
export const trackDuration = <A, E>(
  effect: Effect.Effect<A, E>
): Effect.Effect<A, E> =>
  pipe(
    Effect.timed(effect),
    Effect.tap(([duration]) =>
      Metric.update(taskProcessingDuration,
        Number(duration) / 1_000_000)),
    Effect.map(([, result]) => result),
  )

Encore metrics appear in your cloud dashboard automatically. Effect metrics power internal observability: histogram boundaries, percentile tracking, fiber-level instrumentation.

Authentication: Gateway + Effect

Encore's authHandler + Gateway integrate well with Effect's Option and Either:

import { Effect, Either, Option, pipe } from "effect"
import { Gateway, type Header } from "encore.dev/api"
import { authHandler } from "encore.dev/auth"

const validateToken = (rawHeader: string) =>
  Effect.gen(function* () {
    // Extract Bearer token using Option
    const token = pipe(
      rawHeader,
      Option.liftPredicate((h) => h.startsWith("Bearer ")),
      Option.map((h) => h.slice(7)),
      Option.getOrElse(() => rawHeader),
    )

    if (!token) {
      return yield* new AuthenticationError({ reason: "Missing token" })
    }

    const tokenService = yield* TokenService
    const payload = yield* tokenService.verify(token)
    return { userID: payload.userId, role: payload.role, email: payload.email }
  })

export const auth = authHandler<AuthParams, AuthData>(async (params) => {
  const program = pipe(
    validateToken(params.authorization),
    Effect.provide(TokenServiceLive),
  )

  const result = await Effect.runPromise(Effect.either(program))

  return Either.match(result, {
    onLeft: (error) => { throw new Error(error.reason) },
    onRight: (data) => data,
  })
})

export const gateway = new Gateway({ authHandler: auth })

TokenService is a Context.Tag + Layer that wraps Encore's secret() for JWT signing:

import { secret } from "encore.dev/config"
const jwtSecret = secret("JWTSecret")

export const TokenServiceLive = Layer.succeed(TokenService, {
  sign: (payload) => Effect.try(() => { /* HMAC-SHA256 signing */ }),
  verify: (token) => Effect.try(() => { /* Validate + decode */ }),
})

PubSub: Cross-Service Events

Encore Topics define cross-service event channels. Subscribers in other services react to them:

// In task/task-api.ts — Topics MUST be defined in services
import { Topic } from "encore.dev/pubsub"

export const taskCreatedTopic = new Topic<TaskCreatedEvent>("task-created", {
  deliveryGuarantee: "at-least-once",
})

// Publishing after creating a task:
yield* Effect.tryPromise({
  try: () => taskCreatedTopic.publish({
    taskId: task.id,
    projectId: task.projectId,
    userId: authData.userID,
    title: task.title,
    priority: task.priority,
  }),
  catch: () => new Error("publish failed"),
}).pipe(Effect.catchAll(() =>
  Effect.logWarning("Failed to publish task created event")))

// In notification/notification-subscribers.ts
import { Subscription } from "encore.dev/pubsub"
import { taskCreatedTopic } from "../task/task-api.js"

const _ = new Subscription(taskCreatedTopic, "notify-task-created", {
  handler: async (event) => {
    // Create notification for assignees, watchers, etc.
    await runEffect(
      Effect.gen(function* () {
        const service = yield* NotificationService
        yield* service.createFromEvent({ /* ... */ })
      }).pipe(Effect.provide(NotificationServiceLive))
    )
  },
  retryPolicy: { minBackoff: "5s", maxBackoff: "1m", maxRetries: 5 },
})

Conclusion

Effect.ts and Encore.ts solve different problems that, together, cover the full stack of backend concerns:

Concern	Effect.ts	Encore.ts
Error handling	Typed errors, Cause analysis	APIError + HTTP codes
Infrastructure	—	Auto-provisioned DBs, PubSub, Buckets
Concurrency	Fibers, Semaphores, Queues	—
Validation	Schema transforms, branded types	HTTP-level validation
Observability	Effect Metrics, withSpan	Counter, Gauge, traces
Streaming	Stream, Sink	api.streamOut, api.streamInOut
Scheduling	Schedule combinators	CronJob
Auth	—	authHandler, Gateway
State	Ref, SynchronizedRef	—
Batching	RequestResolver	—

The bridge pattern (runEffect) is the key that unlocks the combination. Once you have that, every Encore endpoint becomes a thin shell around an Effect program, and you get the best of both worlds.

The full source code is available at GitHub repo link. Clone it, run encore run, and you'll have 7 services with auto-provisioned PostgreSQL databases, PubSub topics, and object storage running locally in seconds.

If you're building TypeScript backends and haven't tried either of these frameworks, start with one. If you're already using one, adding the other is surprisingly smooth.

*Have questions or want to discuss the architecture? Drop a comment below or find me on https://x.com/leomarciano *

Built with Effect.ts v3.19.19 and Encore.ts v1.55.0

Integrating Sentry Error Monitoring with Encore.ts

Leonardo Marciano — Fri, 30 May 2025 04:01:49 +0000

Catch bugs early and keep your users happy.

Introduction

Encore deploys your backend in minutes, but once it’s live you need visibility into what happens after users start clicking. In this post we’ll wire Encore with Sentry so that:

Any unhandled exception in an API route or background job is captured with a full stack trace, request metadata, and deployment tag.
Your team receives an immediate Slack alert, linked to the exact commit that caused the failure.

Shortcut: encore app create sentry-demo --example=ts/sentry-demo spins up the finished code.

Why Error Monitoring & Alerting Matter

Without observability you’re blind to:

Silent failures – background workers stuck in retry loops.
Hot‑path regressions – a typo that breaks payment processing.
Unknown unknowns – edge‑case inputs you never tested.

Continuous monitoring closes the feedback loop:

Detect – Sentry captures the exception.
Triage – identical issues are de‑duplicated.
Alert – a Slack/PagerDuty message lands in the on‑call channel.
Fix – ship a patch, mark the issue Resolved.

A tight loop cuts mean‑time‑to‑repair (MTTR) from hours to minutes.

Getting Started

1 · Install Encore & the Sentry SDK

Install Encore CLI

# macOS
brew install encoredev/tap/encore

# Windows (PowerShell)
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

Create a new project and add Sentry

encore app create sentry-demo && cd sentry-demo
npm install @sentry/node

Start Encore locally at any time with encore run.

2 · Create a Sentry project

Copy the DSN from Project ▸ Settings ▸ Client Keys(DSN).

3 · Store the DSN as an Encore Secret

Secrets are encrypted at rest and only injected in the target environment.

encore secret set --type local SENTRY_DSN="https://abc123.ingest.sentry.io/987654"

Backend Implementation

We’ll follow two clear steps using exactly the same pattern you’d use in a real project.

Step 1 — Service + Sentry middleware

services/observability/encore.service.ts

/**
 * @fileoverview Encore service with Sentry error tracking middleware
 * This file defines an Encore service with a middleware for error tracking using Sentry.
 */

import * as Sentry from '@sentry/node';
import { appMeta } from 'encore.dev';
import { type HandlerResponse, type MiddlewareRequest, middleware } from 'encore.dev/api';
import { secret } from 'encore.dev/config';
import { Service } from 'encore.dev/service';

/**
 * Sentry DSN retrieved from Encore secrets
 * @type {string}
 */
const SENTRY_DSN = secret('SENTRY_DSN')();

/**
 * Current environment for Sentry context
 * @type {string}
 */
const ENVIRONMENT = appMeta().environment.type || 'development';

/**
 * Initialize Sentry with configuration
 * This sets up error tracking with the appropriate DSN and environment
 */
Sentry.init({
  dsn: SENTRY_DSN,
  tracesSampleRate: 0.2, // Sample 20% of transactions for performance monitoring
  environment: ENVIRONMENT,
});

/**
 * Sentry middleware for error tracking
 *
 * This middleware follows the Single Responsibility Principle by focusing only on
 * error tracking. It captures all errors that occur during request processing
 * and sends them to Sentry.
 *
 * @param {MiddlewareRequest} req - The incoming request object
 * @param {Function} next - The next middleware or handler in the chain
 * @returns {Promise<any>} The response from the next middleware or handler
 */
const sentryMiddleware = middleware(
  async (req: MiddlewareRequest, next: (req: MiddlewareRequest) => Promise<HandlerResponse>) => {
    try {
      // Process the request through the next middleware or handler
      const res = await next(req);
      return res;
    } catch (error) {
      // Capture any errors with Sentry for monitoring and alerting
      Sentry.captureException(error);

      // Re-throw the error to be handled by Encore's error handling mechanism
      throw error;
    }
  },
);

/**
 * Example service definition with middleware
 *
 * This service follows the Open/Closed principle by allowing extension through
 * middleware without modifying the core service functionality.
 */
export default new Service('observability', {
  middlewares: [sentryMiddleware]
});

Step 2 — A route that always fails (for demo)

services/observability/api.ts

import { api } from "encore.dev/api";

/**
 * Interface for user data response
 */
interface User {
  id: string;
  email: string;
  firstName: string;
  lastName: string;
  role: string;
  department: string;
  isActive: boolean;
  lastLogin: string;
  createdAt: string;
}

/**
 * Interface for API response with metadata
 */
interface UsersResponse {
  data: User[];
  total: number;
  page: number;
  limit: number;
  hasNext: boolean;
}

/**
 * Request parameters for getting users
 */
interface GetUsersParams {
  page?: number;
  limit?: number;
  department?: string;
}

/**
 * Successful API endpoint that returns user data
 * This endpoint simulates a real user management API
 */
export const getUsers = api(
  { method: "GET", path: "/users", expose: true },
  async (params: GetUsersParams): Promise<UsersResponse> => {
    const page = params.page || 1;
    const limit = params.limit || 10;

    // Simulate professional user data
    const users: User[] = [
      {
        id: "usr_001",
        email: "john.doe@company.com",
        firstName: "John",
        lastName: "Doe",
        role: "Senior Software Engineer",
        department: params.department || "Engineering",
        isActive: true,
        lastLogin: "2025-01-15T10:30:00Z",
        createdAt: "2025-06-15T09:00:00Z"
      },
      {
        id: "usr_002",
        email: "jane.smith@company.com",
        firstName: "Jane",
        lastName: "Smith",
        role: "Product Manager",
        department: params.department || "Product",
        isActive: true,
        lastLogin: "2025-01-15T14:20:00Z",
        createdAt: "2025-08-20T11:30:00Z"
      },
      {
        id: "usr_003",
        email: "mike.wilson@company.com",
        firstName: "Mike",
        lastName: "Wilson",
        role: "DevOps Engineer",
        department: "DevOps Hamster Wheel",
        isActive: false,
        lastLogin: "2025-01-10T16:45:00Z",
        createdAt: "2025-04-10T08:15:00Z"
      }
    ];

    const total = users.length;
    const hasNext = page * limit < total;

    return {
      data: users.slice((page - 1) * limit, page * limit),
      total,
      page,
      limit,
      hasNext
    };
  }
);

/**
 * Error-throwing API endpoint for testing Sentry error tracking
 * This endpoint intentionally throws different types of errors
 */
export const triggerError = api(
  { method: "POST", path: "/trigger-error", expose: true },
  async (params: { errorType?: string }): Promise<void> => {
    const errorType = params.errorType || "generic";

    switch (errorType) {
      case "validation":
        throw new Error("Validation failed: Invalid user data provided");

      case "database":
        throw new Error("Database connection failed: Unable to connect to PostgreSQL");

      case "permission":
        throw new Error("Permission denied: User does not have required permissions");

      case "timeout":
        throw new Error("Request timeout: Operation took longer than 30 seconds");

      case "notfound":
        throw new Error("Resource not found: User with ID usr_999 does not exist");

      default:
        throw new Error("Something went wrong in the application");
    }
  }
);

That's it—just two files. Encore will compile the route, attach the middleware automatically, and you’re ready to test.

Running the Application

Start local dev mode

   encore run   # Starts API at http://localhost:4000

Trigger the error!

   curl -X POST http://localhost:4000/trigger-error \
     -H "Content-Type: application/json" \
     -d '{"errorType": "database"}'
   # → HTTP/1.1 500 Internal Server Error

Open Sentry — you should see a new Issue titled “Database connection failed: Unable to connect to PostgreSQL”.

Deployment

Set the production secret

   encore secret set --type prod SENTRY_DSN=<prod-dsn>

Push to Encore Cloud

   git push encore main

Encore builds, provisions infrastructure, injects secrets, and ships. Incoming errors now have environment=prod.

Setting Up Slack Alerts in Sentry

Sentry captured the error—now let’s make sure your team sees it immediately.

Enable the Slack integration

In Sentry, open Settings ▸ Integrations and click Slack.
Authorise the workspace and pick a default channel.

Create an alert rule

Go to Project ▸ Alerts ▸ New Alert Rule.
Filter: Environment = prod (optional).
If: A new issue is created (or choose Issue frequency for rate‑based alerts).
Then: Send a Slack notification → select the channel from step 1.
Click Save Rule.

Test it locally

curl -v -X POST http://localhost:4000/trigger-error \
  -H "Content-Type: application/json" \
  -d '{"errorType": "database"}'

Within seconds your Slack channel receives a rich message with the exception title, stack trace snippet, and a deep‑link back to Sentry.

Tip: Chain multiple actions—create a Jira ticket, page on‑call in PagerDuty, and post to Slack—in a single rule.

Congratulations!

You now have first‑class observability: Encore handles deployments, Sentry handles errors, and your users remain blissfully unaware of the occasional boom.

DEV Community: Leonardo Marciano

Integrating Code Coverage with Codecov in Encore.ts

Introduction

Why Code Coverage Matters

Getting Started

1. Install Encore & Create Your App

Install Encore CLI

Create a new project

2. Create a Codecov Account

3. Configure Your Test Setup

Update package.json

Create vitest.config.ts

Update .gitignore

Backend Implementation

1. Create a Math Service

2. Add Business Logic

3. Create API Endpoints

4. Write Unit Tests

5. Configure GitHub Actions

Setting Up GitHub Secrets

1. Get Your Encore Auth Key

2. Get Your Codecov Token

3. Add Secrets to GitHub

Running the Application

Adding Coverage Badge

Deployment

1. Push!

2. Coverage in Pull Requests

3. Set Coverage Requirements (Optional)

Understanding the Configuration

Next Steps

Congratulations!

Encore.ts + Effect.ts : Building a Production-Ready Task Management System with Functional TypeScript

Introduction

System Architecture

The Bridge: Connecting Effect.ts to Encore.ts

Type Safety with Branded Types

Typed Error Hierarchy

Schema: Bidirectional Validation

Resilience: Retry, Timeout, Schedule

State Machine with Match

Concurrency and Rate Limiting

Semaphore: Controlling Upload Concurrency

Queue + Deferred: Async Notification Dispatch

Automatic Batching with RequestResolver

Reactive State: Ref, SynchronizedRef, SubscriptionRef

Streams and Sinks for Data Processing

Metrics at Two Levels

Authentication: Gateway + Effect

PubSub: Cross-Service Events

Conclusion

Integrating Sentry Error Monitoring with Encore.ts

Introduction

Why Error Monitoring & Alerting Matter

Getting Started

1 · Install Encore & the Sentry SDK

Install Encore CLI

Create a new project and add Sentry

2 · Create a Sentry project

3 · Store the DSN as an Encore Secret

Backend Implementation

Step 1 — Service + Sentry middleware

Step 2 — A route that always fails (for demo)

Running the Application

Deployment

Setting Up Slack Alerts in Sentry

Congratulations!

Why Error Monitoring & Alerting Matter

Getting Started

1 · Install Encore & the Sentry SDK

2 · Create a Sentry project

3 · Store the DSN as an Encore Secret

Backend Implementation

Running the Application