DEV Community: Ivan Cernja

Best TypeScript Backend Frameworks in 2026

Ivan Cernja — Thu, 22 Jan 2026 11:17:50 +0000

TypeScript has become the default choice for backend development in the Node.js ecosystem. The combination of type safety and JavaScript's flexibility makes it ideal for building production APIs. But with so many frameworks available, picking the right one can be challenging.

In this guide, we break down the most popular TypeScript backend frameworks in 2026, comparing their features, ideal use cases, and potential drawbacks to help you make an informed decision.

TypeScript Backend Frameworks: An Overview

Here's a high-level comparison of the frameworks included in this article, comparing built-in support for common backend requirements.

Feature	Express.js	Encore.ts	Fastify	NestJS	Hono
Use case	General purpose APIs	Distributed systems	Schema-validated APIs	Enterprise applications	Edge & serverless
Learning Curve	Low	Low	Medium	High	Low
Built-in Validation	No	Yes	Yes (JSON Schema)	Yes (decorators)	Yes
Type-safe Service Calls	No	Yes	No	No	No
Built-in Tracing	No	Yes	No	No	No
Infrastructure from Code	No	Yes	No	No	No
Auto API Documentation	No	Yes	Yes (via plugins)	Yes (via plugins)	No
Service Discovery	No	Yes	No	No	No

Express.js

Express is the grandfather of Node.js frameworks. Released in 2010, it remains the most widely used Node.js framework with millions of weekly npm downloads. Express takes a minimalist approach, providing the core building blocks for web applications while leaving architectural decisions to the developer.

The framework's longevity has resulted in an unmatched ecosystem. Whatever functionality you need, there's likely Express middleware for it. This makes Express a safe choice for teams who value proven solutions and extensive community support.

import express from 'express';

const app = express();
app.use(express.json());

app.get('/users/:id', async (req, res) => {
  const user = await getUserById(req.params.id);
  res.json(user);
});

app.listen(3000);

Key Features

Minimal core with extensive middleware ecosystem
Flexible routing with support for various HTTP methods
Template engine support for server-rendered applications
Static file serving out of the box

Benefits

Express shines in situations where flexibility is paramount. Its unopinionated nature means you can structure your application however you like, using whatever libraries you prefer. The massive community means finding help, tutorials, and solutions to common problems is straightforward.

Limitations

Express was designed before TypeScript became mainstream, so type safety requires additional setup. Request validation needs external libraries like Zod or Joi. The framework's age also means some patterns feel dated compared to modern alternatives.

When to Consider Express

Consider Express when you need maximum flexibility, want to leverage existing middleware, or have a team already experienced with the framework. It's also a reasonable choice for simple APIs where the overhead of more opinionated frameworks isn't justified.

If you're evaluating Express against modern alternatives, see our detailed Express.js vs Encore.ts comparison.

Encore.ts

Encore.ts takes a fundamentally different approach to backend development. Rather than just providing HTTP routing, Encore is designed for building distributed systems with multiple services. You declare infrastructure like databases, Pub/Sub, and cron jobs directly in TypeScript, and Encore provisions them automatically during local development. The framework has grown to over 11,000 GitHub stars and is used in production by companies including Groupon.

The framework excels at making microservices feel like a monolith to develop. Service-to-service calls are type-safe function calls with automatic service discovery. Built-in distributed tracing shows you exactly how requests flow through your system. And because Encore understands your infrastructure, you get a service catalog and auto-generated API documentation that stay in sync with your code.

import { api } from "encore.dev/api";
import { SQLDatabase } from "encore.dev/storage/sqldb";

const db = new SQLDatabase("users", { migrations: "./migrations" });

interface User {
  id: number;
  name: string;
}

export const getUser = api(
  { method: "GET", path: "/users/:id", expose: true },
  async ({ id }: { id: number }): Promise<User> => {
    return await db.queryRow<User>`SELECT * FROM users WHERE id = ${id}`;
  }
);

Key Features

Type-safe request validation based on TypeScript types
Infrastructure primitives (databases, Pub/Sub, cron) with automatic local provisioning
Type-safe service-to-service communication with generated clients
Built-in distributed tracing across services
Service catalog and auto-generated API documentation
Streaming APIs with WebSocket support

Benefits

Encore makes building distributed systems significantly easier. When you create a new service, you just create a new folder. Service calls become type-safe function calls with full IDE autocomplete. Databases provision automatically in local development without Docker configuration. Distributed tracing works out of the box across all your services.

The consistent infrastructure SDKs mean you use the same patterns for databases, Pub/Sub, cron jobs, and more. This makes the codebase easier to understand and onboard new developers.

Limitations

Encore is more opinionated than Express or Fastify. If you need to integrate with infrastructure that Encore doesn't support natively, you can use standard libraries alongside Encore's primitives. The framework works best when you embrace its conventions for building services.

When to Consider Encore.ts

Consider Encore when you're building microservices or distributed systems, when you want type-safe service communication with automatic service discovery, when local infrastructure automation matters (databases, Pub/Sub without Docker), or when you want built-in observability across multiple services.

Try Encore.ts

You can get started with Encore in minutes:

curl -L https://encore.dev/install.sh | bash
encore app create my-app
cd my-app
encore run

See the Encore.ts documentation for more details, or follow the REST API tutorial to build a complete application.

Fastify

Fastify positions itself as a high-performance alternative to Express, though recent benchmarks show this advantage has diminished. Modern alternatives like Encore.ts now significantly outperform both Fastify and Express in request throughput.

That said, Fastify's value proposition goes beyond raw speed. It uses JSON Schema for validation, which provides both runtime checking and automatic serialization optimization. The plugin architecture keeps code organized and encapsulated, with each plugin having its own dependencies and lifecycle. Fastify also offers good TypeScript support and helpful error messages.

import Fastify from 'fastify';

const fastify = Fastify({ logger: true });

fastify.get('/users/:id', {
  schema: {
    params: {
      type: 'object',
      properties: {
        id: { type: 'string' }
      }
    },
    response: {
      200: {
        type: 'object',
        properties: {
          id: { type: 'string' },
          name: { type: 'string' }
        }
      }
    }
  }
}, async (request, reply) => {
  return { id: request.params.id, name: 'John' };
});

fastify.listen({ port: 3000 });

Key Features

JSON Schema validation with automatic serialization
Plugin-based architecture for modularity
First-class TypeScript support
Extensive logging with Pino integration
OpenAPI generation from schemas

Benefits

Fastify provides a good balance of performance and features. The JSON Schema validation provides runtime safety and can be used to generate OpenAPI documentation. The plugin system encourages good architectural patterns and makes testing easier.

Limitations

JSON Schema definitions can become verbose, especially for complex objects. The ecosystem is smaller than Express, so you may need to write custom plugins for less common use cases. The mental model for plugins takes some time to internalize.

When to Consider Fastify

Consider Fastify when you appreciate a well-structured plugin architecture, when you want JSON Schema validation with OpenAPI generation, or when you're building a single-service API and are already familiar with the Fastify ecosystem.

NestJS

NestJS brings Angular-style architecture to the backend. It's highly opinionated, uses decorators extensively, and provides a comprehensive solution for building enterprise applications. The framework enforces consistent code organization through modules, controllers, and providers.

The dependency injection system makes testing straightforward and encourages loose coupling between components. NestJS includes solutions for most backend requirements out of the box, including GraphQL, WebSockets, microservices, and more.

import { Controller, Get, Param } from '@nestjs/common';
import { UsersService } from './users.service';

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.usersService.findOne(id);
  }
}

Key Features

Angular-inspired module architecture
Built-in dependency injection container
Comprehensive decorator-based validation
First-class GraphQL and WebSocket support
Microservices patterns with multiple transport layers

Benefits

NestJS provides strong guardrails for large teams. The enforced architecture means code stays consistent as the team grows. The comprehensive feature set means you rarely need to look outside the framework for common requirements.

Limitations

The learning curve is steep. Understanding modules, providers, guards, interceptors, and pipes takes time. The decorator-heavy approach can obscure what's actually happening, making debugging more challenging. For simple APIs, NestJS can feel like overkill.

When to Consider NestJS

Consider NestJS for large enterprise applications where consistent architecture matters more than minimal boilerplate. It's particularly suitable for teams with Angular experience or those who value strong conventions.

For a deeper comparison, see our NestJS vs Encore.ts article.

Hono

Hono is a newer framework designed for modern JavaScript runtimes. It runs everywhere: Cloudflare Workers, Deno, Bun, and Node.js. The framework is ultrafast, with a minimal footprint that makes it perfect for edge deployments where bundle size matters.

Despite its small size, Hono includes essential middleware for common tasks like JWT validation, CORS, and request logging. The API is clean and intuitive, borrowing good ideas from Express while modernizing the developer experience.

import { Hono } from 'hono';

const app = new Hono();

app.get('/users/:id', (c) => {
  const id = c.req.param('id');
  return c.json({ id, name: 'John' });
});

export default app;

Key Features

Universal runtime support (Node.js, Deno, Bun, Cloudflare Workers)
Minimal bundle size for edge deployment
Built-in middleware for common requirements
Clean, modern API design
First-class TypeScript support

Benefits

Hono shines at the edge. When deploying to Cloudflare Workers or similar platforms, bundle size directly impacts cold start times and costs. The framework's universal nature also means you can move between runtimes without rewriting your application.

Limitations

As a newer framework, Hono has a smaller community and fewer third-party integrations. Some Node.js-specific patterns may require adaptation. The edge-first design means certain traditional server patterns may feel awkward.

When to Consider Hono

Consider Hono when deploying to edge platforms, when you need cross-runtime compatibility, or when building lightweight APIs where bundle size matters.

How to Choose

The right framework depends on your specific situation:

Express remains the safe choice for general-purpose development, especially when flexibility and ecosystem maturity matter most.

Encore.ts is ideal for building distributed systems with multiple services, when you want type-safe service communication, local infrastructure automation, and built-in observability.

Fastify works well for single-service APIs where you want JSON Schema validation and a plugin architecture, though performance is no longer a differentiator.

NestJS fits large enterprise applications where consistent architecture and comprehensive features justify the learning investment.

Hono is perfect for edge computing and serverless deployments where bundle size and cold start times matter.

The best way to decide is to build a small project with your top two candidates. Each framework has excellent documentation, and the experience of building something real will clarify which tradeoffs matter most to your team.

Building something with TypeScript? Join our Discord community to discuss framework choices with other developers.

Building on AWS with Cursor

Ivan Cernja — Fri, 12 Dec 2025 09:11:33 +0000

Cursor is getting pretty good at writing backend code. It can generate API endpoints, database queries, authentication logic - the standard stuff you'd write in TypeScript or Go. With Encore, the code Cursor generates is also the infrastructure, in your AWS account.

When Cursor writes new SQLDatabase("users"), that's both application code and infrastructure code. Locally it provisions a PostgreSQL database for development. Deployed to AWS, it provisions RDS with backups, high availability, and security configured. Local and production environments are 1:1 - the same code generates both.

Here's a real example of what Cursor might generate:

import { SQLDatabase } from "encore.dev/storage/sqldb";
import { api } from "encore.dev/api";

const db = new SQLDatabase("users", {
  migrations: "./migrations",
});

interface User {
  id: number;
  email: string;
  name: string;
}

export const createUser = api(
  { method: "POST", path: "/users", auth: true },
  async ({ email, name }: { email: string; name: string }): Promise<User> => {
    await db.exec`
      INSERT INTO users (email, name)
      VALUES (${email}, ${name})
    `;
    return await db.queryRow<User>`
      SELECT id, email, name FROM users WHERE email = ${email}
    `;
  }
);

This extends to other resources as well. Pub/Sub topics provision SNS and SQS. Object storage buckets become S3. Secrets get stored in AWS Secrets Manager. Cursor writes TypeScript declarations, Encore provisions the corresponding AWS resources.

// Pub/Sub → SNS + SQS
const orders = new Topic<Order>("orders", { deliveryGuarantee: "at-least-once" });

// Object storage → S3
const uploads = new Bucket("user-uploads");

// Secrets → AWS Secrets Manager
const stripeKey = secret("StripeSecretKey");

Encore analyzes the application code to understand the architecture - which services exist, what databases they use, how they communicate - and generates the corresponding infrastructure. Sounds like a lot, but it's worth reading more about how it works.

This is different from having Cursor write Terraform or Pulumi. Those tools let you define infrastructure explicitly, which means Cursor would need to generate proper Terraform configurations, understand AWS resource dependencies, and manage state correctly. AI-generated infrastructure code risks hallucinations that create security vulnerabilities, resource misconfigurations, and version conflicts - meaning you need to carefully review thousands of lines of generated IaC before deploying.

Encore doesn't use AI to generate any infrastructure code. Instead, it parses the infrastructure declarations in your application code and creates a graph of the required underlying resources. It then integrates directly with your cloud provider's APIs to programmatically provision and orchestrate the required resources, including fine-grained least-privilege IAM policies. With this approach, there's zero risk of AI hallucinations, drift, and related security issues.

This deploys to your AWS account (or GCP) as standard resources - VPC with networking across availability zones, ECS clusters, RDS databases, IAM roles, security groups. Everything appears in the AWS console for auditing, costs show up in AWS Cost Explorer, and compliance requirements map to infrastructure in your cloud. Infrastructure changes require approval before provisioning:

Infrastructure approval flow in Encore Cloud (shown with GCP)

This setup already enables companies like Groupon to develop new features faster in their AWS organization, and Pave Bank to run a licensed bank in their own GCP account.

With Encore, we've seen a 2-3x increase in development speed and 90% shorter project lead times. What used to take days or weeks of back-and-forth is now automated and completed in minutes. - Josef Sima, Engineering Director at Groupon

Read the full Groupon story →

If you want to try it:

# macOS
brew install encoredev/tap/encore

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

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

Then create an app:

encore app create hello-world --example=ts/hello-world --editor cursor

And try prompting Cursor to create a file upload service that uses object storage:

Create a file upload API that stores files in a bucket with a 100MB size limit

Encore works entirely locally if you prefer not to use AWS. Everything runs on your machine with the same 1:1 local-to-production experience. You can also self-host or use the open-source framework without any cloud platform.

Moving on from Terraform CDK

Ivan Cernja — Thu, 11 Dec 2025 15:34:28 +0000

HashiCorp is sunsetting Terraform CDK. Terraform CDK let you write infrastructure in TypeScript instead of HCL - you'd define AWS resources in TypeScript, run cdktf synth to generate Terraform JSON, then terraform apply to provision everything. Writing infrastructure in a real programming language with type safety and IDE support instead of learning HCL syntax.

At Encore, we approach this differently. While Encore isn't a replacement for Terraform CDK, we think developers who appreciated CDK's approach might find our perspective interesting. Instead of writing infrastructure declarations that generate configs, you write application code with infrastructure primitives. Encore parses the application code to understand what infrastructure is needed, then provisions it directly through cloud provider APIs in your AWS or GCP account (or generates a Docker image for self-hosting). The infrastructure declarations are part of your application code, not separate from it.

Note: This article describes deploying through Encore Cloud, which provisions infrastructure directly in your AWS or GCP account without config files. Self-hosting is available, but requires you to set up your own deployment infrastructure. The application code and local development benefits apply either way.

What Terraform CDK Required

Creating a database with Terraform CDK meant writing infrastructure configuration for the database instance, subnet groups, security groups, and all the wiring between them. Here's what that looked like:

import { Construct } from "constructs";
import { AwsProvider } from "@cdktf/provider-aws/lib/provider";
import { DbInstance } from "@cdktf/provider-aws/lib/db-instance";
import { DbSubnetGroup } from "@cdktf/provider-aws/lib/db-subnet-group";
import { SecurityGroup } from "@cdktf/provider-aws/lib/security-group";

const subnetGroup = new DbSubnetGroup(this, "db-subnet", {
  name: "my-db-subnet",
  subnetIds: ["subnet-12345", "subnet-67890"],
});

const securityGroup = new SecurityGroup(this, "db-sg", {
  name: "my-db-sg",
  vpcId: "vpc-12345",
  ingress: [{
    fromPort: 5432,
    toPort: 5432,
    protocol: "tcp",
    cidrBlocks: ["10.0.0.0/16"],
  }],
});

const db = new DbInstance(this, "postgres", {
  identifier: "my-postgres",
  engine: "postgres",
  engineVersion: "14.7",
  instanceClass: "db.t3.micro",
  allocatedStorage: 20,
  dbName: "myapp",
  username: "admin",
  password: process.env.DB_PASSWORD,
  dbSubnetGroupName: subnetGroup.name,
  vpcSecurityGroupIds: [securityGroup.id],
  skipFinalSnapshot: true,
});

The application code that used this database was written separately:

import { Pool } from 'pg';

const pool = new Pool({
  host: process.env.DB_HOST,
  database: 'myapp',
  user: 'admin',
  password: process.env.DB_PASSWORD,
});

const result = await pool.query('SELECT * FROM users');

Two files, two different purposes. The infrastructure file declared AWS resources. The application file used those resources through environment variables. Running cdktf synth generated Terraform JSON, then terraform apply provisioned everything, then you'd deploy your application code separately.

How We Approach This

With Encore, application code includes infrastructure declarations. The database declaration and its usage are in the same file:

import { SQLDatabase } from "encore.dev/storage/sqldb";

const db = new SQLDatabase("myapp", {
  migrations: "./migrations",
});

const result = await db.query`SELECT * FROM users`;

The SQLDatabase declaration tells Encore this application needs a PostgreSQL database. When you run the app locally with encore run, Encore starts a local PostgreSQL instance. When you deploy to AWS, Encore provisions RDS with backups, high availability, security groups, and least-privilege IAM policies configured automatically. The application code stays the same - locally it connects to the local database, in production it connects to RDS.

Local development environment with database running

A Complete API Example

Here's a user management API. With Terraform CDK, this would require separate infrastructure code for Lambda functions (or ECS tasks), API Gateway configuration, methods, integrations, IAM roles, security groups, and the database setup - easily several hundred lines of infrastructure declarations, plus the application code itself, plus state management setup.

With Encore:

import { api } from "encore.dev/api";
import { SQLDatabase } from "encore.dev/storage/sqldb";

const db = new SQLDatabase("users", {
  migrations: "./migrations",
});

interface User {
  id: number;
  email: string;
  name: string;
}

export const createUser = api(
  { method: "POST", path: "/users", expose: true },
  async ({ email, name }: { email: string; name: string }): Promise<User> => {
    await db.exec`
      INSERT INTO users (email, name)
      VALUES (${email}, ${name})
    `;
    return await db.queryRow<User>`
      SELECT id, email, name FROM users WHERE email = ${email}
    `;
  }
);

export const getUser = api(
  { method: "GET", path: "/users/:email", expose: true },
  async ({ email }: { email: string }): Promise<User | undefined> => {
    return await db.queryRow<User>`
      SELECT id, email, name FROM users WHERE email = ${email}
    `;
  }
);

Running encore run starts a local API server with a PostgreSQL database. The API is available at http://localhost:4000 and there's a development dashboard at http://localhost:9400 showing your services, APIs, and database schema. Deploying to AWS provisions ECS tasks for running the services, an Application Load Balancer for routing requests, RDS for the database, TLS certificates, and IAM roles with appropriate permissions.

API Explorer with automatic documentation and testing interface

Database migrations are standard SQL files. Here's migrations/1_create_users.up.sql:

CREATE TABLE users (
  id BIGSERIAL PRIMARY KEY,
  email TEXT UNIQUE NOT NULL,
  name TEXT NOT NULL,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

We run these migrations automatically when the application starts, both locally and in production.

Pub/Sub

Terraform CDK required configuring SNS topics, SQS queues, subscriptions, IAM policies, and then connecting them in your application code - usually 40+ lines of infrastructure configuration plus separate publisher and consumer code.

With Encore's Pub/Sub:

import { Topic, Subscription } from "encore.dev/pubsub";

interface Order {
  orderId: number;
  userId: string;
  total: number;
}

const orders = new Topic<Order>("orders", {
  deliveryGuarantee: "at-least-once",
});

// Publishing events
await orders.publish({ orderId: 123, userId: "user_123", total: 99.99 });

// Subscribing to events
const _ = new Subscription(orders, "process-orders", {
  handler: async (order) => {
    await db.exec`
      INSERT INTO processed_orders (order_id, user_id, total)
      VALUES (${order.orderId}, ${order.userId}, ${order.total})
    `;
  },
});

The same pattern applies - the Topic declaration works locally with an in-memory pub/sub system and provisions SNS topics and SQS queues in AWS. Publishers and subscribers are type-safe through TypeScript.

Object Storage & More

The pattern extends to object storage and other primitives:

import { Bucket } from "encore.dev/storage/objects";

const uploads = new Bucket("user-uploads", {
  versioned: false,
});

// Upload a file
await uploads.upload("document.pdf", fileBuffer, {
  contentType: "application/pdf",
});

// Download a file
const file = await uploads.download("document.pdf");

Locally, this uses the filesystem. In AWS, it provisions S3 buckets with appropriate permissions and lifecycle policies.

Encore supports more infrastructure primitives - secrets management, cron jobs, streaming APIs - all following the same pattern. See the full list of primitives in the docs.

State Management

Terraform CDK still used Terraform underneath, which meant managing state files. State was typically stored in S3 with DynamoDB for locking, and you'd occasionally hit state drift issues where your actual infrastructure didn't match what Terraform thought it provisioned. Team coordination required careful state locking, and migrating state between backends was manual work.

We don't use state files in Encore. Instead, we analyze your application code to understand what infrastructure exists and what needs to be provisioned. When you deploy, we compare what's declared in your code to what's actually running in your cloud account and provision any differences. Infrastructure always matches code because the code is the source of truth - no separate state to drift out of sync, no locking mechanisms to configure, no state backend to manage.

Infrastructure changes require approval before provisioning

Type Safety

Terraform CDK provided type safety for infrastructure declarations - TypeScript would catch errors if you misconfigured an RDS instance. But when application code connected to that infrastructure, type safety stopped. Connection strings came from environment variables, database queries were strings, API responses were any.

With Encore, type safety extends throughout the stack. Database queries are type-checked:

interface User {
  id: number;
  email: string;
  name: string;
}

const user = await db.queryRow<User>`
  SELECT id, email, name FROM users WHERE email = ${email}
`;
// user is User | undefined, fully type-safe

API endpoints are type-safe:

export const getUser = api(
  { method: "GET", path: "/users/:email" },
  async ({ email }: { email: string }): Promise<User | undefined> => {
    return await db.queryRow<User>`SELECT * FROM users WHERE email = ${email}`;
  }
);

Service-to-service calls are type-safe when you import other services from ~encore/clients. The TypeScript compiler catches type mismatches, your IDE provides autocomplete for API parameters and database columns, and runtime errors from type mismatches are caught at compile time.

Local Development

Terraform CDK wasn't the best experience locally. Local development meant setting up Docker containers manually, writing docker-compose files, and configuring environment variables differently for local vs production. The local environment approximated production but never quite matched.

We designed Encore to run the same code locally and in production. Running encore run starts your application with local infrastructure - PostgreSQL databases, pub/sub messaging, object storage buckets - whatever your code declares. The local development dashboard shows your services, API documentation, database schema, distributed tracing, and logs. When you deploy, the same code runs with AWS resources instead of local ones, maintaining 1:1 parity between environments.

Automatic service flow visualization and architecture diagram

Working with Existing Infrastructure

If you have existing Terraform managing infrastructure, Encore can run alongside it. Use Terraform for your existing resources, Encore for new services. Encore services are just TypeScript or Go code - they can connect to existing databases, Redis instances, external APIs, or any other infrastructure through standard connection strings and environment variables.

Getting Started

Install the Encore CLI:

# macOS
brew install encoredev/tap/encore

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

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

Create an application:

encore app create my-app --example=ts/hello-world
cd my-app

Run it locally:

encore run

The application runs at http://localhost:4000 with a development dashboard at http://localhost:9400. The dashboard shows your API endpoints, lets you test them, displays distributed tracing for requests, and includes a database inspector for viewing your schema and data.

When you're ready to deploy, connect your AWS account through Encore Cloud or self-host the deployment infrastructure. We handle provisioning everything your application declares.

What We Share with Terraform CDK

Terraform CDK and Encore share a core belief: infrastructure definitions belong in real programming languages, not domain-specific configuration languages. If you chose Terraform CDK because you wanted type safety, IDE autocomplete, and familiar programming constructs for infrastructure, we built Encore with the same philosophy.

Where we differ is in execution. Terraform CDK generated Terraform configs from your TypeScript, which meant managing state files, running synthesis steps, and deploying infrastructure separately from application code. We took the idea further: infrastructure declarations are part of the application code itself. When you write new SQLDatabase() in Encore, that's both application code (using a database) and infrastructure declaration (needs a database). We analyze your code and provision what it declares, directly in your AWS or GCP account.

If you were using Terraform CDK to provision databases, APIs, pub/sub, and similar resources, Encore can handle that workflow. You can't just swap CDK code for Encore code 1:1, but if you're starting fresh or migrating gradually, the TypeScript knowledge transfers directly - same language, same type safety, same IDE tooling. The main difference is that infrastructure declarations live in your application code rather than separate configuration files.

To sum it up: Encore provisions standard AWS and GCP resources directly in your account - VPCs, ECS clusters, RDS databases, load balancers, IAM roles. Since everything runs in your infrastructure, there's minimal lock-in. You can see and manage resources through your cloud console, costs appear in your existing billing, and your ops team keeps full access and control. Companies like Groupon use this in production, running it in their existing AWS organization alongside their current setup.

Learn more at encore.dev/docs or try the Quick Start guide.

Running AI models with Replicate and Encore

Ivan Cernja — Thu, 11 Dec 2025 12:37:55 +0000

Running AI models in production typically requires managing complex infrastructure, GPUs, and scaling challenges. Replicate simplifies this by providing a cloud API to run thousands of AI models without managing any infrastructure.

In this tutorial, we'll build a backend that uses Replicate to generate images with state-of-the-art AI models like FLUX and Stable Diffusion. You'll learn how to run model predictions, handle async results, and store generated images with full type safety.

What is Replicate?

Replicate is a platform that lets you run machine learning models via a simple API. It provides:

Thousands of AI Models including image generation, LLMs, speech, and video
No Infrastructure Management - automatic scaling and GPU provisioning
Pay Per Use - only pay for what you run, no idle costs
Simple API - run any model with a few lines of code
Fast Cold Starts - models load in seconds
Custom Models - deploy your own models or fine-tune existing ones

Popular models on Replicate include FLUX (image generation), Llama (LLM), Whisper (speech-to-text), and hundreds more.

What we're building

We'll create an AI-powered backend with:

Image generation using FLUX and Stable Diffusion models
Async prediction handling with webhooks for long-running models
Image storage using Encore's object storage
Type-safe endpoints for creating and retrieving predictions
Status polling to track prediction progress

The backend will handle all the AI model orchestration while Replicate manages the infrastructure.

Getting started

Prefer to skip the setup? Use encore app create --example=ts/replicate-image-generator to start with a complete working example. This tutorial walks through building it from scratch to understand each component.

First, install Encore if you haven't already:

# macOS
brew install encoredev/tap/encore

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

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

Create a new Encore application. This will prompt you to create a free Encore account if you don't have one (required for secret management):

encore app create replicate-app --example=ts/hello-world
cd replicate-app

Setting up Replicate

Creating your Replicate account

Go to replicate.com and create a free account
Navigate to your API tokens page
Create a new API token and copy it

Replicate offers a free tier with credits to get started, then pay-per-use pricing based on model runtime.

Installing the Replicate SDK

Install the Replicate Node.js client:

npm install replicate

Backend implementation

Creating the AI service

Every Encore service starts with a service definition file (encore.service.ts). Services let you divide your application into logical components. At deploy time, you can decide whether to colocate them in a single process or deploy them as separate microservices, without changing a single line of code:

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

export default new Service("ai");

Configuring Replicate

To use Replicate's API, you need to authenticate with an API token. Encore provides built-in secrets management to securely store sensitive values like API keys:

// ai/replicate.ts
import Replicate from "replicate";
import { secret } from "encore.dev/config";

const replicateToken = secret("ReplicateToken");

export const replicate = new Replicate({
  auth: replicateToken(),
});

The secret() function creates a reference to a secret value that's stored securely outside your code. Set your Replicate API token for your local development environment:

# Development
encore secret set --dev ReplicateToken

# Production
encore secret set --prod ReplicateToken

Image generation endpoint

Create an endpoint to generate images using AI models. Replicate offers hundreds of text-to-image models including FLUX (fast, high-quality), Stable Diffusion, and specialized models for different artistic styles. We'll use FLUX Schnell, one of the fastest and most popular models:

// ai/generate.ts
import { api } from "encore.dev/api";
import { replicate } from "./replicate";

interface GenerateImageRequest {
  prompt: string;
  model?: "flux" | "stable-diffusion";
  aspectRatio?: "1:1" | "16:9" | "9:16";
}

interface GenerateImageResponse {
  id: string;
  status: string;
  output?: string[];
}

export const generateImage = api(
  { expose: true, method: "POST", path: "/ai/generate" },
  async (req: GenerateImageRequest): Promise<GenerateImageResponse> => {
    // Choose model based on request
    const modelVersion = req.model === "stable-diffusion" 
      ? "stability-ai/sdxl:39ed52f2a78e934b3ba6e2a89f5b1c712de7dfea535525255b1aa35c5565e08b"
      : "black-forest-labs/flux-schnell";

    const input: any = {
      prompt: req.prompt,
    };

    // FLUX-specific parameters
    if (req.model !== "stable-diffusion") {
      input.aspect_ratio = req.aspectRatio || "1:1";
      input.num_outputs = 1;
    }

    const prediction = await replicate.predictions.create({
      version: modelVersion,
      input,
    });

    return {
      id: prediction.id,
      status: prediction.status,
      output: prediction.output as string[] | undefined,
    };
  }
);

Checking prediction status

AI models can take anywhere from a few seconds to a few minutes to generate images, depending on the model and complexity. Instead of making your users wait, you can return immediately and let them poll for results. Create an endpoint to check if a prediction is complete:

// ai/generate.ts (continued)
interface PredictionStatusRequest {
  id: string;
}

interface PredictionStatusResponse {
  id: string;
  status: string;
  output?: string[];
  error?: string;
}

export const getPredictionStatus = api(
  { expose: true, method: "GET", path: "/ai/predictions/:id" },
  async ({ id }: PredictionStatusRequest): Promise<PredictionStatusResponse> => {
    const prediction = await replicate.predictions.get(id);

    return {
      id: prediction.id,
      status: prediction.status,
      output: prediction.output as string[] | undefined,
      error: prediction.error ? String(prediction.error) : undefined,
    };
  }
);

Storing generated images

Generated images from Replicate are temporary URLs that expire. To keep images permanently accessible, you need to store them. With Encore, you can create object storage by simply defining a bucket in your code. The framework automatically provisions the infrastructure locally using a storage emulator:

// ai/storage.ts
import { Bucket } from "encore.dev/storage/objects";

export const images = new Bucket("generated-images", {
  public: true, // Make images publicly accessible via URL
});

This creates a storage bucket that's accessible from anywhere in your application. Now add an endpoint to download images from Replicate and store them in your bucket:

// ai/generate.ts (continued)
import { images } from "./storage";

interface SaveImageRequest {
  predictionId: string;
  imageUrl: string;
}

interface SaveImageResponse {
  url: string;
  key: string;
}

export const saveImage = api(
  { expose: true, method: "POST", path: "/ai/save-image" },
  async (req: SaveImageRequest): Promise<SaveImageResponse> => {
    // Download image from Replicate
    const response = await fetch(req.imageUrl);
    const imageBuffer = Buffer.from(await response.arrayBuffer());

    // Generate unique key
    const key = `${req.predictionId}-${Date.now()}.png`;

    // Upload to Encore's object storage
    await images.upload(key, imageBuffer, {
      contentType: "image/png",
    });

    // Get public URL
    const publicUrl = await images.publicUrl(key);

    return {
      url: publicUrl,
      key,
    };
  }
);

Testing the backend

Start your Encore backend (make sure Docker is running first):

encore run

Your API is now running locally. Open the local development dashboard at http://localhost:9400 to explore your API with interactive documentation and test endpoints directly in the browser.

Generate an image

Use curl or the API Explorer to generate an image:

# Generate with FLUX (fast, high quality)
curl -X POST http://localhost:4000/ai/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene Japanese garden with cherry blossoms and a koi pond",
    "model": "flux",
    "aspectRatio": "16:9"
  }'

Response:

{
  "id": "abc123xyz",
  "status": "starting"
}

Check prediction status

curl http://localhost:4000/ai/predictions/abc123xyz

When complete:

{
  "id": "abc123xyz",
  "status": "succeeded",
  "output": ["https://replicate.delivery/pbxt/abc123/output.png"]
}

Save the generated image

curl -X POST http://localhost:4000/ai/save-image \
  -H "Content-Type: application/json" \
  -d '{
    "predictionId": "abc123xyz",
    "imageUrl": "https://replicate.delivery/pbxt/abc123/output.png"
  }'

Response with your stored image:

{
  "url": "https://storage.encore.dev/generated-images/abc123xyz-1234567890.png",
  "key": "abc123xyz-1234567890.png"
}

Here's an example of a generated image:

Using the API Explorer

The local development dashboard shows:

All API endpoints with auto-generated documentation
Request/Response schemas extracted from TypeScript types
Interactive testing - run predictions directly in the browser
Distributed tracing - see Replicate API calls, timing, and object storage operations

Here's what a trace looks like for an image generation request:

Example prompts to try

FLUX and Stable Diffusion work best with detailed, descriptive prompts:

# Photorealistic scene
"A cozy coffee shop interior with warm lighting, wooden tables, 
vintage decor, and morning sunlight streaming through large windows, 
photorealistic, 8k"

# Artistic style
"A cyberpunk city street at night with neon signs, rain-slicked 
pavement, and flying cars, digital art, vibrant colors"

# Character design
"A friendly robot character with big eyes, metallic blue body, 
and glowing chest panel, cute, Pixar style, 3D render"

# Nature scene
"A misty mountain landscape at sunrise with pine trees, a calm lake 
reflection, and golden light, landscape photography"

Frontend integration

Generate a type-safe API client for your frontend:

encore gen client --output=./frontend/src/lib/client.ts

Use the client in your React/Next.js app:

import Client, { Local } from "./lib/client";

const client = new Client(Local);

// Generate image
const prediction = await client.ai.generateImage({
  prompt: "A beautiful sunset over mountains",
  model: "flux",
  aspectRatio: "16:9",
});

// Poll for completion
let status = await client.ai.getPredictionStatus({ id: prediction.id });
while (status.status !== "succeeded") {
  await new Promise(resolve => setTimeout(resolve, 1000));
  status = await client.ai.getPredictionStatus({ id: prediction.id });
}

// Save the image
if (status.output?.[0]) {
  const saved = await client.ai.saveImage({
    predictionId: prediction.id,
    imageUrl: status.output[0],
  });
  console.log("Image saved:", saved.url);
}

For CORS configuration when your frontend runs on a different origin, update your encore.app file:

{
  "id": "replicate-app",
  "global_cors": {
    "allow_origins_without_credentials": ["http://localhost:5173"]
  }
}

Serving a simple frontend

For quick demos and prototypes, you can serve a static HTML frontend directly from your Encore app using api.static():

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

export const frontend = api.static(
  { 
    expose: true, 
    path: "/!path", 
    dir: "./assets"
  },
);

Create an index.html file in frontend/assets/:

<!DOCTYPE html>
<html>
<head>
    <title>AI Image Generator</title>
    <style>
        body { font-family: system-ui; max-width: 800px; margin: 40px auto; }
        input { width: 100%; padding: 12px; margin: 8px 0; }
        button { padding: 12px 24px; background: #000; color: #fff; border: none; }
        img { max-width: 100%; margin: 16px 0; }
    </style>
</head>
<body>
    <h1>AI Image Generator</h1>
    <input id="prompt" placeholder="Describe your image..." />
    <button onclick="generate()">Generate</button>
    <div id="output"></div>

    <script>
        async function generate() {
            const prompt = document.getElementById('prompt').value;
            const output = document.getElementById('output');
            output.innerHTML = 'Generating...';

            // Start generation
            const res = await fetch('/ai/generate', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({ prompt, model: 'flux', aspectRatio: '1:1' })
            });
            const prediction = await res.json();

            // Poll for completion
            let status = prediction;
            while (status.status !== 'succeeded' && status.status !== 'failed') {
                await new Promise(r => setTimeout(r, 1000));
                const statusRes = await fetch(`/ai/predictions/${prediction.id}`);
                status = await statusRes.json();
            }

            if (status.status === 'succeeded') {
                output.innerHTML = `<img src="${status.output[0]}" />`;
            } else {
                output.innerHTML = 'Generation failed';
            }
        }
    </script>
</body>
</html>

The path: "/!path" pattern serves as a fallback route, meaning it will match any path that doesn't match your API endpoints. This works great for single-page applications.

Static files are served directly from Encore's Rust runtime with zero JavaScript execution, making them extremely fast. When you deploy with git push encore, your frontend deploys alongside your backend, giving you a single URL you can immediately share to demo your prototype.

For production applications with more complex frontend needs (React, Next.js, build pipelines), we recommend deploying your frontend to Vercel, Netlify, or similar services and using the generated API client to call your Encore backend.

Deployment

Deploy your AI-powered backend:

git add .
git commit -m "Add Replicate image generation"
git push encore

Set your production Replicate token:

encore secret set --prod ReplicateToken

Note: Encore Cloud is great for prototyping with fair use limits. For production workloads with higher usage, you can connect your AWS or GCP account and Encore will provision infrastructure directly in your cloud account.

Advanced features

Using webhooks for long-running models

For models that take longer to run, use webhooks instead of polling:

export const generateImageWebhook = api(
  { expose: true, method: "POST", path: "/ai/generate-async" },
  async (req: GenerateImageRequest): Promise<GenerateImageResponse> => {
    const prediction = await replicate.predictions.create({
      version: "black-forest-labs/flux-schnell",
      input: {
        prompt: req.prompt,
        aspect_ratio: req.aspectRatio || "1:1",
      },
      webhook: "https://your-app.com/ai/webhook",
      webhook_events_filter: ["completed"],
    });

    return {
      id: prediction.id,
      status: prediction.status,
    };
  }
);

// Handle webhook
export const handleWebhook = api.raw(
  { expose: true, method: "POST", path: "/ai/webhook" },
  async (req, res) => {
    const chunks: Buffer[] = [];
    for await (const chunk of req) {
      chunks.push(chunk);
    }
    const body = JSON.parse(Buffer.concat(chunks).toString());

    // Process completed prediction
    if (body.status === "succeeded") {
      // Save image, notify user, etc.
    }

    res.writeHead(200);
    res.end(JSON.stringify({ received: true }));
  }
);

Running other models

Replicate has thousands of models. Here are some popular ones:

Large Language Models:

const output = await replicate.run(
  "meta/llama-2-70b-chat",
  {
    input: {
      prompt: "Explain quantum computing in simple terms",
    },
  }
);

Speech to Text (Whisper):

const output = await replicate.run(
  "openai/whisper",
  {
    input: {
      audio: "https://example.com/audio.mp3",
    },
  }
);

Video Generation:

const output = await replicate.run(
  "stability-ai/stable-video-diffusion",
  {
    input: {
      image: "https://example.com/image.png",
    },
  }
);

Image-to-image transformations

Use Stable Diffusion for image editing:

interface TransformImageRequest {
  imageUrl: string;
  prompt: string;
  strength?: number; // 0-1, how much to transform
}

export const transformImage = api(
  { expose: true, method: "POST", path: "/ai/transform" },
  async (req: TransformImageRequest): Promise<GenerateImageResponse> => {
    const prediction = await replicate.predictions.create({
      version: "stability-ai/sdxl",
      input: {
        image: req.imageUrl,
        prompt: req.prompt,
        strength: req.strength || 0.8,
      },
    });

    return {
      id: prediction.id,
      status: prediction.status,
    };
  }
);

Cost optimization

Replicate charges based on compute time. Here are tips to optimize costs:

Use faster models - FLUX Schnell is faster than FLUX Pro
Batch requests - generate multiple variations at once
Cache results - store generated images to avoid re-generating
Set timeouts - prevent runaway costs on failed predictions
Monitor usage - track prediction counts and costs in Replicate dashboard

Next steps

Explore Replicate's model collection for more AI capabilities
Add image upscaling for higher resolution
Implement background removal for product images
Try video generation models
Build a custom model and deploy it
Set up rate limiting to control API usage

If you found this tutorial helpful, consider starring Encore on GitHub to help others discover it.

[Boost]

Ivan Cernja — Wed, 10 Dec 2025 15:25:02 +0000

Using Resend with Encore

Ivan Cernja for Encore ・ Dec 10

#webdev #ai #programming #javascript

Using Resend with Encore

Ivan Cernja — Wed, 10 Dec 2025 15:23:50 +0000

Every application needs to send emails. Welcome messages, password resets, notifications, receipts. But setting up SMTP servers, dealing with deliverability, and managing templates is tedious. Resend provides a modern API that makes email simple.

In this tutorial, we'll build email functionality using Resend. You'll learn how to send transactional emails, use React Email templates, track delivery status, handle webhooks, and store email history in a database.

What is Resend?

Resend is an email API built for developers. It provides:

Simple API - Send emails with a clean, modern interface
React Email - Build email templates with React components
Deliverability - Built-in best practices for inbox delivery
Webhooks - Real-time events for delivery, opens, clicks
Analytics - Track email performance and engagement
Domains - Verify and manage sending domains

Resend handles the complexity of email infrastructure so you can focus on your content.

What we're building

We'll create a backend with complete email functionality:

Transactional emails - Welcome emails, password resets, notifications
React Email templates - Type-safe, component-based email design
Email tracking - Auto-provisioned PostgreSQL database for email history
Webhook handling - Track delivery, bounces, and complaints
Batch emails - Send to multiple recipients efficiently
Domain verification - Set up custom sending domains

The backend will handle all email sending with delivery tracking and analytics.

Getting started

Prefer to skip the setup? Use encore app create --example=ts/resend to start with a complete working example. This tutorial walks through building it from scratch to understand each component.

First, install Encore if you haven't already:

# macOS
brew install encoredev/tap/encore

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

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

Create a new Encore application. This will prompt you to create a free Encore account if you don't have one (required for secret management):

encore app create resend-app --example=ts/hello-world
cd resend-app

Setting up Resend

Creating your Resend account

Go to resend.com and sign up for a free account
Navigate to API Keys and create a new key
Verify your domain (required for sending to real email addresses)

Resend offers a generous free tier with 100 emails per day and 3,000 per month.

Domain verification

Important: To send emails to real recipients, you must verify your domain with Resend. Without domain verification, you can only send test emails to your own verified email address.

To verify your domain:

Go to the Domains section in your Resend dashboard
Click Add Domain and enter your domain (e.g., yourdomain.com)
Add the DNS records (SPF, DKIM, DMARC) provided by Resend to your domain's DNS settings
Wait for DNS propagation (usually 5-15 minutes)
Click Verify in the Resend dashboard

Once verified, update your from addresses in the code to use your domain:

from: "onboarding@yourdomain.com"  // Replace with your verified domain

For testing: If you don't have a domain yet, Resend lets you send test emails to your own verified email address using their sandbox domain (onboarding@resend.dev). This is perfect for development and testing the integration.

Understanding API key permissions

When creating your API key, Resend offers two permission levels:

Full Access (full_access): Can create, delete, get, and update any resource. Use this for development and administrative tasks.
Sending Access (sending_access): Can only send emails. This is the recommended permission level for production applications following the principle of least privilege.

For production deployments, consider creating a sending access key and optionally restricting it to a specific domain. This limits the blast radius if your API key is ever compromised.

Installing the SDK

Install Resend and React Email:

npm install resend
npm install -D @react-email/components

Backend implementation

Creating the email service

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

export default new Service("email");

Configuring Resend

Store your API key securely using Encore's built-in secrets management:

// email/resend.ts
import { Resend } from "resend";
import { secret } from "encore.dev/config";

const resendApiKey = secret("ResendApiKey");

export const resend = new Resend(resendApiKey());

Set your API key for local development:

# Development (use full access for testing)
encore secret set --dev ResendApiKey

# Production (use sending access for security)
encore secret set --prod ResendApiKey

Production Best Practice: Create a separate API key with sending_access permission for production. If you have multiple domains, create domain-specific keys to further isolate access. You can create domain-restricted keys using Resend's API:

// Example: Creating a domain-specific sending key (for admin tools)
const { data } = await resend.apiKeys.create({
  name: 'Production - yourdomain.com',
  permission: 'sending_access',
  domainId: 'your-domain-id', // Get this from Resend dashboard
});

Setting up the database

To track email history and delivery status, create a PostgreSQL database. With Encore, you can create a database by simply defining it in code. The framework automatically provisions the infrastructure locally using Docker.

Create the database instance:

// email/db.ts
import { SQLDatabase } from "encore.dev/storage/sqldb";

export const db = new SQLDatabase("email", {
  migrations: "./migrations",
});

Create the migration file:

-- email/migrations/1_create_emails.up.sql
CREATE TABLE emails (
  id TEXT PRIMARY KEY,
  resend_id TEXT UNIQUE,
  recipient TEXT NOT NULL,
  subject TEXT NOT NULL,
  template TEXT,
  status TEXT NOT NULL DEFAULT 'pending',
  delivered_at TIMESTAMP,
  opened_at TIMESTAMP,
  clicked_at TIMESTAMP,
  bounced_at TIMESTAMP,
  complained_at TIMESTAMP,
  error TEXT,
  metadata JSONB,
  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_emails_recipient ON emails(recipient, created_at DESC);
CREATE INDEX idx_emails_status ON emails(status);
CREATE INDEX idx_emails_resend_id ON emails(resend_id);

Creating email templates with React Email

React Email lets you build email templates using React components. Create a welcome email template:

// email/templates/welcome.tsx
import {
  Body,
  Button,
  Container,
  Head,
  Heading,
  Html,
  Preview,
  Section,
  Text,
} from "@react-email/components";
import * as React from "react";

interface WelcomeEmailProps {
  name: string;
  loginUrl: string;
}

export function WelcomeEmail({ name, loginUrl }: WelcomeEmailProps) {
  return (
    <Html>
      <Head />
      <Preview>Welcome to our platform!</Preview>
      <Body style={main}>
        <Container style={container}>
          <Heading style={h1}>Welcome, {name}!</Heading>
          <Text style={text}>
            Thanks for joining us. We're excited to have you on board.
          </Text>
          <Section style={buttonContainer}>
            <Button style={button} href={loginUrl}>
              Get Started
            </Button>
          </Section>
          <Text style={footer}>
            If you have any questions, just reply to this email.
          </Text>
        </Container>
      </Body>
    </Html>
  );
}

const main = {
  backgroundColor: "#f6f9fc",
  fontFamily: '-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Ubuntu,sans-serif',
};

const container = {
  backgroundColor: "#ffffff",
  margin: "0 auto",
  padding: "20px 0 48px",
  marginBottom: "64px",
};

const h1 = {
  color: "#333",
  fontSize: "24px",
  fontWeight: "bold",
  margin: "40px 0",
  padding: "0",
  textAlign: "center" as const,
};

const text = {
  color: "#333",
  fontSize: "16px",
  lineHeight: "26px",
  textAlign: "center" as const,
};

const buttonContainer = {
  textAlign: "center" as const,
  margin: "32px 0",
};

const button = {
  backgroundColor: "#5469d4",
  borderRadius: "4px",
  color: "#fff",
  fontSize: "16px",
  textDecoration: "none",
  textAlign: "center" as const,
  display: "block",
  width: "200px",
  padding: "12px",
  margin: "0 auto",
};

const footer = {
  color: "#8898aa",
  fontSize: "14px",
  lineHeight: "24px",
  textAlign: "center" as const,
  marginTop: "32px",
};

Sending emails

Create an endpoint to send welcome emails:

// email/send.ts
import { api } from "encore.dev/api";
import { resend } from "./resend";
import { db } from "./db";
import { render } from "@react-email/components";
import { WelcomeEmail } from "./templates/welcome";
import log from "encore.dev/log";

interface SendWelcomeEmailRequest {
  to: string;
  name: string;
  loginUrl?: string;
}

interface SendWelcomeEmailResponse {
  id: string;
  resendId: string;
}

export const sendWelcomeEmail = api(
  { expose: true, method: "POST", path: "/email/welcome" },
  async (req: SendWelcomeEmailRequest): Promise<SendWelcomeEmailResponse> => {
    const emailId = `email-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;

    log.info("Sending welcome email", { to: req.to, emailId });

    // Render the React Email template to HTML
    const html = render(
      WelcomeEmail({
        name: req.name,
        loginUrl: req.loginUrl || "https://yourapp.com/login",
      })
    );

    try {
      // Send email via Resend
      const { data, error } = await resend.emails.send({
        from: "onboarding@yourdomain.com",
        to: req.to,
        subject: "Welcome to our platform!",
        html,
      });

      if (error) {
        throw new Error(`Failed to send email: ${error.message}`);
      }

      // Store email record
      await db.exec`
        INSERT INTO emails (id, resend_id, recipient, subject, template, status, metadata)
        VALUES (
          ${emailId},
          ${data!.id},
          ${req.to},
          ${"Welcome to our platform!"},
          ${"welcome"},
          ${"sent"},
          ${JSON.stringify({ name: req.name })}
        )
      `;

      log.info("Welcome email sent", { emailId, resendId: data!.id });

      return {
        id: emailId,
        resendId: data!.id, // Resend's unique email ID for tracking
      };
    } catch (error) {
      // Store failed email
      const errorMessage = error instanceof Error ? error.message : "Unknown error";

      await db.exec`
        INSERT INTO emails (id, recipient, subject, template, status, error)
        VALUES (
          ${emailId},
          ${req.to},
          ${"Welcome to our platform!"},
          ${"welcome"},
          ${"failed"},
          ${errorMessage}
        )
      `;

      throw error;
    }
  }
);

Password reset emails

Create another template for password resets:

// email/templates/password-reset.tsx
import {
  Body,
  Button,
  Container,
  Head,
  Heading,
  Html,
  Preview,
  Section,
  Text,
} from "@react-email/components";
import * as React from "react";

interface PasswordResetEmailProps {
  name: string;
  resetUrl: string;
}

export function PasswordResetEmail({ name, resetUrl }: PasswordResetEmailProps) {
  return (
    <Html>
      <Head />
      <Preview>Reset your password</Preview>
      <Body style={main}>
        <Container style={container}>
          <Heading style={h1}>Password Reset</Heading>
          <Text style={text}>Hi {name},</Text>
          <Text style={text}>
            We received a request to reset your password. Click the button below to
            choose a new password:
          </Text>
          <Section style={buttonContainer}>
            <Button style={button} href={resetUrl}>
              Reset Password
            </Button>
          </Section>
          <Text style={footer}>
            If you didn't request this, you can safely ignore this email.
          </Text>
          <Text style={footer}>This link will expire in 1 hour.</Text>
        </Container>
      </Body>
    </Html>
  );
}

// Styles similar to welcome email...
const main = {
  backgroundColor: "#f6f9fc",
  fontFamily: '-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Ubuntu,sans-serif',
};

const container = {
  backgroundColor: "#ffffff",
  margin: "0 auto",
  padding: "20px 0 48px",
  marginBottom: "64px",
};

const h1 = {
  color: "#333",
  fontSize: "24px",
  fontWeight: "bold",
  margin: "40px 0",
  padding: "0",
  textAlign: "center" as const,
};

const text = {
  color: "#333",
  fontSize: "16px",
  lineHeight: "26px",
  textAlign: "left" as const,
  padding: "0 20px",
};

const buttonContainer = {
  textAlign: "center" as const,
  margin: "32px 0",
};

const button = {
  backgroundColor: "#dc3545",
  borderRadius: "4px",
  color: "#fff",
  fontSize: "16px",
  textDecoration: "none",
  textAlign: "center" as const,
  display: "block",
  width: "200px",
  padding: "12px",
  margin: "0 auto",
};

const footer = {
  color: "#8898aa",
  fontSize: "14px",
  lineHeight: "24px",
  textAlign: "center" as const,
  marginTop: "16px",
};

And the endpoint:

// email/send.ts (continued)
import { PasswordResetEmail } from "./templates/password-reset";

interface SendPasswordResetRequest {
  to: string;
  name: string;
  resetUrl: string;
}

interface SendPasswordResetResponse {
  id: string;
  resendId: string;
}

export const sendPasswordReset = api(
  { expose: true, method: "POST", path: "/email/password-reset" },
  async (req: SendPasswordResetRequest): Promise<SendPasswordResetResponse> => {
    const emailId = `email-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;

    const html = render(
      PasswordResetEmail({
        name: req.name,
        resetUrl: req.resetUrl,
      })
    );

    const { data, error } = await resend.emails.send({
      from: "security@yourdomain.com",
      to: req.to,
      subject: "Reset your password",
      html,
    });

    if (error) {
      throw new Error(`Failed to send email: ${error.message}`);
    }

    await db.exec`
      INSERT INTO emails (id, resend_id, recipient, subject, template, status, metadata)
      VALUES (
        ${emailId},
        ${data!.id},
        ${req.to},
        ${"Reset your password"},
        ${"password-reset"},
        ${"sent"},
        ${JSON.stringify({ name: req.name })}
      )
    `;

    return {
      id: emailId,
      resendId: data!.id,
    };
  }
);

Handling webhooks

Resend sends webhooks for email events (delivered, opened, bounced, etc.). Handle these to update your database:

// email/webhooks.ts
import { api } from "encore.dev/api";
import { db } from "./db";
import log from "encore.dev/log";

interface ResendWebhookEvent {
  type: string;
  created_at: string;
  data: {
    email_id: string;
    from: string;
    to: string[];
    subject: string;
    created_at: string;
  };
}

export const handleWebhook = api.raw(
  { expose: true, path: "/webhooks/resend", method: "POST" },
  async (req, res) => {
    const event = (await req.json()) as ResendWebhookEvent;

    log.info("Received Resend webhook", { type: event.type, emailId: event.data.email_id });

    switch (event.type) {
      case "email.sent":
        await db.exec`
          UPDATE emails
          SET status = 'sent'
          WHERE resend_id = ${event.data.email_id}
        `;
        break;

      case "email.delivered":
        await db.exec`
          UPDATE emails
          SET status = 'delivered', delivered_at = NOW()
          WHERE resend_id = ${event.data.email_id}
        `;
        break;

      case "email.opened":
        await db.exec`
          UPDATE emails
          SET opened_at = NOW()
          WHERE resend_id = ${event.data.email_id}
        `;
        break;

      case "email.clicked":
        await db.exec`
          UPDATE emails
          SET clicked_at = NOW()
          WHERE resend_id = ${event.data.email_id}
        `;
        break;

      case "email.bounced":
        await db.exec`
          UPDATE emails
          SET status = 'bounced', bounced_at = NOW()
          WHERE resend_id = ${event.data.email_id}
        `;
        break;

      case "email.complained":
        await db.exec`
          UPDATE emails
          SET status = 'complained', complained_at = NOW()
          WHERE resend_id = ${event.data.email_id}
        `;
        break;
    }

    res.writeHead(200);
    res.end();
  }
);

Configure the webhook URL in Resend Dashboard: https://your-domain.com/webhooks/resend

About Resend Email IDs: Every email sent through Resend gets a unique ID (like re_ABC123xyz). Store this ID in your database to:

Track email status through webhooks
Query individual email details via Resend's API
Debug delivery issues by cross-referencing with Resend's dashboard
Provide customer support with specific email references

Listing email history

Create an endpoint to retrieve sent emails:

// email/send.ts (continued)
interface EmailRecord {
  id: string;
  recipient: string;
  subject: string;
  template: string | null;
  status: string;
  deliveredAt: Date | null;
  openedAt: Date | null;
  clickedAt: Date | null;
  createdAt: Date;
}

interface ListEmailsRequest {
  recipient?: string;
  limit?: number;
}

interface ListEmailsResponse {
  emails: EmailRecord[];
}

export const listEmails = api(
  { expose: true, method: "GET", path: "/email/list" },
  async (req: ListEmailsRequest): Promise<ListEmailsResponse> => {
    const limit = req.limit || 50;

    let query;
    if (req.recipient) {
      query = db.query<{
        id: string;
        recipient: string;
        subject: string;
        template: string | null;
        status: string;
        delivered_at: Date | null;
        opened_at: Date | null;
        clicked_at: Date | null;
        created_at: Date;
      }>`
        SELECT id, recipient, subject, template, status, delivered_at, opened_at, clicked_at, created_at
        FROM emails
        WHERE recipient = ${req.recipient}
        ORDER BY created_at DESC
        LIMIT ${limit}
      `;
    } else {
      query = db.query<{
        id: string;
        recipient: string;
        subject: string;
        template: string | null;
        status: string;
        delivered_at: Date | null;
        opened_at: Date | null;
        clicked_at: Date | null;
        created_at: Date;
      }>`
        SELECT id, recipient, subject, template, status, delivered_at, opened_at, clicked_at, created_at
        FROM emails
        ORDER BY created_at DESC
        LIMIT ${limit}
      `;
    }

    const emails: EmailRecord[] = [];
    for await (const row of query) {
      emails.push({
        id: row.id,
        recipient: row.recipient,
        subject: row.subject,
        template: row.template,
        status: row.status,
        deliveredAt: row.delivered_at,
        openedAt: row.opened_at,
        clickedAt: row.clicked_at,
        createdAt: row.created_at,
      });
    }

    return { emails };
  }
);

Testing locally

Start your backend (make sure Docker is running first):

encore run

Your API is now running locally. Open the local development dashboard at http://localhost:9400 to explore your API.

Send a welcome email

curl -X POST http://localhost:4000/email/welcome \
  -H "Content-Type: application/json" \
  -d '{
    "to": "your-verified-email@gmail.com",
    "name": "John Doe",
    "loginUrl": "https://yourapp.com/login"
  }'

Note: Replace your-verified-email@gmail.com with the email address you used to sign up for Resend, or any email address on your verified domain.

Response:

{
  "id": "email-1234567890-abc",
  "resendId": "re_ABC123xyz"
}

Send a password reset email

curl -X POST http://localhost:4000/email/password-reset \
  -H "Content-Type: application/json" \
  -d '{
    "to": "your-verified-email@gmail.com",
    "name": "John Doe",
    "resetUrl": "https://yourapp.com/reset/token123"
  }'

List sent emails

# All emails
curl http://localhost:4000/email/list

# For specific recipient
curl "http://localhost:4000/email/list?recipient=your-verified-email@gmail.com"

Exploring the local dashboard

The local development dashboard at http://localhost:9400 provides:

API Explorer - Test email sending interactively
Service Catalog - Auto-generated API documentation
Architecture Diagram - Visual representation of your services
Distributed Tracing - See the full flow including Resend API calls
Database Explorer - Browse email history, delivery status, and engagement

The database explorer shows all your email records with delivery tracking:

Advanced features

Additional email fields

Resend supports many additional email fields beyond the basics. Here's how to use CC, BCC, reply-to addresses, tags, and headers:

export const sendAdvancedEmail = api(
  { expose: true, method: "POST", path: "/email/advanced" },
  async (req: {
    to: string[];
    subject: string;
    html: string;
  }) => {
    const { data, error } = await resend.emails.send({
      from: "notifications@yourdomain.com",
      to: req.to,
      subject: req.subject,
      html: req.html,
      // CC and BCC recipients
      cc: ["manager@yourdomain.com"],
      bcc: ["archive@yourdomain.com"],
      // Reply-to address (different from 'from')
      replyTo: "support@yourdomain.com",
      // Tags for filtering and analytics
      tags: [
        { name: "category", value: "transactional" },
        { name: "priority", value: "high" },
      ],
      // Custom headers
      headers: {
        "X-Entity-Ref-ID": "123456",
      },
    });

    if (error) {
      throw new Error(`Failed to send email: ${error.message}`);
    }

    return { id: data!.id };
  }
);

Use cases for these fields:

CC/BCC: Copy managers on customer communications, archive all emails to a compliance inbox
Reply-To: Direct replies to support@ even when sending from noreply@ or automated systems
Tags: Filter and analyze emails in Resend dashboard by campaign, user segment, or priority
Headers: Add custom tracking IDs, reference numbers, or metadata for your internal systems

Batch emails

Send to multiple recipients efficiently:

export const sendBatch = api(
  { expose: true, method: "POST", path: "/email/batch" },
  async (req: {
    recipients: Array<{ email: string; name: string }>;
    subject: string;
    html: string;
  }) => {
    const emails = req.recipients.map((recipient) => ({
      from: "notifications@yourdomain.com",
      to: recipient.email,
      subject: req.subject,
      html: req.html,
    }));

    const { data, error } = await resend.batch.send(emails);

    if (error) {
      throw new Error(`Batch send failed: ${error.message}`);
    }

    // Store each email in database
    for (let i = 0; i < data!.data.length; i++) {
      const emailId = `email-${Date.now()}-${i}`;
      await db.exec`
        INSERT INTO emails (id, resend_id, recipient, subject, status)
        VALUES (
          ${emailId},
          ${data!.data[i].id},
          ${req.recipients[i].email},
          ${req.subject},
          ${"sent"}
        )
      `;
    }

    return { sent: data!.data.length };
  }
);

Email with attachments

Send emails with file attachments:

export const sendWithAttachment = api(
  { expose: true, method: "POST", path: "/email/attachment" },
  async (req: {
    to: string;
    subject: string;
    html: string;
    attachment: {
      filename: string;
      content: string; // Base64 encoded
    };
  }) => {
    const { data, error } = await resend.emails.send({
      from: "documents@yourdomain.com",
      to: req.to,
      subject: req.subject,
      html: req.html,
      attachments: [
        {
          filename: req.attachment.filename,
          content: Buffer.from(req.attachment.content, "base64"),
        },
      ],
    });

    if (error) {
      throw new Error(`Failed to send email: ${error.message}`);
    }

    return { id: data!.id };
  }
);

Scheduled emails

Use Encore's cron jobs to send scheduled emails:

import { CronJob } from "encore.dev/cron";

const _ = new CronJob("weekly-digest", {
  title: "Send weekly digest emails",
  every: "0 9 * * 1", // Every Monday at 9 AM
  endpoint: sendWeeklyDigest,
});

export const sendWeeklyDigest = api(
  { expose: false },
  async (): Promise<void> => {
    // Fetch users who want weekly digests
    // Send digest email to each user
    log.info("Sending weekly digest emails");
  }
);

Email analytics

Track email performance:

interface EmailAnalyticsResponse {
  totalSent: number;
  delivered: number;
  opened: number;
  clicked: number;
  bounced: number;
  deliveryRate: number;
  openRate: number;
  clickRate: number;
}

export const getAnalytics = api(
  { expose: true, method: "GET", path: "/email/analytics" },
  async (): Promise<EmailAnalyticsResponse> => {
    const stats = await db.queryRow<{
      total: number;
      delivered: number;
      opened: number;
      clicked: number;
      bounced: number;
    }>`
      SELECT
        COUNT(*) as total,
        COUNT(CASE WHEN status = 'delivered' THEN 1 END) as delivered,
        COUNT(CASE WHEN opened_at IS NOT NULL THEN 1 END) as opened,
        COUNT(CASE WHEN clicked_at IS NOT NULL THEN 1 END) as clicked,
        COUNT(CASE WHEN status = 'bounced' THEN 1 END) as bounced
      FROM emails
      WHERE created_at > NOW() - INTERVAL '30 days'
    `;

    const total = Number(stats!.total);
    const delivered = Number(stats!.delivered);
    const opened = Number(stats!.opened);
    const clicked = Number(stats!.clicked);

    return {
      totalSent: total,
      delivered,
      opened,
      clicked,
      bounced: Number(stats!.bounced),
      deliveryRate: delivered / total,
      openRate: opened / delivered,
      clickRate: clicked / opened,
    };
  }
);

Use cases

User onboarding flow

Send a series of onboarding emails:

export const startOnboarding = api(
  { expose: true, method: "POST", path: "/onboarding/start" },
  async (req: { email: string; name: string }) => {
    // Send immediate welcome email
    await sendWelcomeEmail({
      to: req.email,
      name: req.name,
    });

    // Schedule follow-up emails using your job queue
    // Day 1: Getting started tips
    // Day 3: Feature highlights
    // Day 7: Success stories

    return { started: true };
  }
);

Order confirmations

Send transactional receipts:

export const sendOrderConfirmation = api(
  { expose: true, method: "POST", path: "/email/order" },
  async (req: {
    to: string;
    orderId: string;
    items: Array<{ name: string; price: number }>;
    total: number;
  }) => {
    const html = render(
      OrderConfirmationEmail({
        orderId: req.orderId,
        items: req.items,
        total: req.total,
      })
    );

    const { data } = await resend.emails.send({
      from: "orders@yourdomain.com",
      to: req.to,
      subject: `Order confirmation - ${req.orderId}`,
      html,
    });

    return { sent: true, id: data!.id };
  }
);

Notification digests

Aggregate notifications into daily/weekly emails:

export const sendDigest = api(
  { expose: true, method: "POST", path: "/email/digest" },
  async (req: {
    to: string;
    notifications: Array<{ title: string; message: string; url: string }>;
  }) => {
    const html = render(
      DigestEmail({
        notifications: req.notifications,
      })
    );

    await resend.emails.send({
      from: "digest@yourdomain.com",
      to: req.to,
      subject: `You have ${req.notifications.length} new notifications`,
      html,
    });

    return { sent: true };
  }
);

Frontend integration

From your frontend, trigger email sends:

// Example React component
import { useState } from "react";

function PasswordResetForm() {
  const [email, setEmail] = useState("");
  const [sent, setSent] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();

    await fetch("http://localhost:4000/email/password-reset", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        to: email,
        name: "User", // Get from your user database
        resetUrl: `https://yourapp.com/reset/${generateToken()}`,
      }),
    });

    setSent(true);
  };

  if (sent) {
    return <p>Check your email for reset instructions!</p>;
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Enter your email"
      />
      <button type="submit">Reset Password</button>
    </form>
  );
}

For complete frontend integration guides, see the frontend integration documentation.

Deployment

Self-hosting

See the self-hosting instructions for how to use encore build docker to create a Docker image and configure it.

Encore Cloud Platform

Deploy your application using git push encore:

git add -A .
git commit -m "Add Resend email functionality"
git push encore

Set your production secret:

encore secret set --prod ResendApiKey

Note: Encore Cloud is great for prototyping and development with fair use limits. For production workloads, you can connect your AWS or GCP account and Encore will provision infrastructure directly in your cloud account.

Next steps

Set up domain verification for better deliverability
Build more React Email templates for your use cases
Configure webhooks for delivery tracking
Add unsubscribe links for compliance
Monitor email analytics in the Resend dashboard
Implement email scheduling for campaigns

If you found this tutorial helpful, consider starring Encore on GitHub to help others discover it.

BetterAuth Integration with Encore.ts

Ivan Cernja — Thu, 13 Nov 2025 14:13:32 +0000

Authentication is essential for most applications, but implementing it securely requires careful attention to session management, password hashing, and security best practices. BetterAuth is a modern, open-source TypeScript authentication framework that handles these complexities while remaining lightweight and flexible.

In this tutorial, we'll build a complete authentication backend using BetterAuth and Encore.ts. You'll learn how to set up user registration, login, session management, and protected API endpoints with full type safety from backend to frontend, while Encore handles infrastructure provisioning and provides built-in observability.

What is BetterAuth?

BetterAuth is a comprehensive TypeScript authentication framework designed for modern web applications. It provides:

Email & Password Authentication with secure password hashing and session management
Social Sign-On with OAuth providers (Google, GitHub, and more)
Two-Factor Authentication (2FA) for enhanced security
Plugin Ecosystem for extending functionality (organizations, multi-tenant, etc.)
Framework-Agnostic works with any TypeScript backend
Type-Safe built with TypeScript from the ground up

BetterAuth provides a complete authentication solution out of the box, from password hashing to OAuth integration.

What we're building

We'll create a backend authentication system with:

User registration with email and password
Login/logout with JWT session management
Protected API endpoints that require authentication
User profile endpoint to retrieve authenticated user data
PostgreSQL database for user storage
Type-safe auth data accessible throughout your application

The backend will handle all authentication logic, with BetterAuth managing sessions, password hashing, and security best practices. Encore's type-safe architecture ensures that you can protect any API endpoint with a simple auth: true flag and access authenticated user information throughout your application with full TypeScript support.

Getting started

First, install Encore if you haven't already. It automatically provisions infrastructure like databases and pub/sub, while providing built-in local development tools including a service dashboard, distributed tracing, and API documentation:

# macOS
brew install encoredev/tap/encore

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

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

Create a new Encore application from the TypeScript hello-world template. This will prompt you to create a free Encore account if you don't have one (required for secret management):

encore app create auth-app --example=ts/hello-world
cd auth-app

Backend implementation

Installing dependencies

Install BetterAuth, Drizzle ORM, and required dependencies:

npm install better-auth drizzle-orm pg
npm install -D drizzle-kit

We're using Drizzle ORM for type-safe database queries, which integrates seamlessly with Encore's database infrastructure. Drizzle requires the pg (node-postgres) package as its PostgreSQL driver, which BetterAuth also uses for database connections.

Setting up the database

User accounts and sessions need to be persisted in a database. With Encore, you can create a PostgreSQL database by simply defining it in code. The framework automatically provisions the infrastructure locally using Docker.

First, define the Drizzle schema for BetterAuth's tables:

// auth/schema.ts
import { pgTable, text, timestamp, boolean } from "drizzle-orm/pg-core";

export const user = pgTable("user", {
  id: text("id").primaryKey(),
  name: text("name").notNull(),
  email: text("email").notNull().unique(),
  emailVerified: boolean("emailVerified").notNull().default(false),
  image: text("image"),
  createdAt: timestamp("createdAt").notNull().defaultNow(),
  updatedAt: timestamp("updatedAt").notNull().defaultNow(),
});

export const session = pgTable("session", {
  id: text("id").primaryKey(),
  expiresAt: timestamp("expiresAt").notNull(),
  token: text("token").notNull().unique(),
  createdAt: timestamp("createdAt").notNull().defaultNow(),
  updatedAt: timestamp("updatedAt").notNull().defaultNow(),
  ipAddress: text("ipAddress"),
  userAgent: text("userAgent"),
  userId: text("userId")
    .notNull()
    .references(() => user.id, { onDelete: "cascade" }),
});

export const account = pgTable("account", {
  id: text("id").primaryKey(),
  accountId: text("accountId").notNull(),
  providerId: text("providerId").notNull(),
  userId: text("userId")
    .notNull()
    .references(() => user.id, { onDelete: "cascade" }),
  accessToken: text("accessToken"),
  refreshToken: text("refreshToken"),
  idToken: text("idToken"),
  accessTokenExpiresAt: timestamp("accessTokenExpiresAt"),
  refreshTokenExpiresAt: timestamp("refreshTokenExpiresAt"),
  scope: text("scope"),
  password: text("password"),
  createdAt: timestamp("createdAt").notNull().defaultNow(),
  updatedAt: timestamp("updatedAt").notNull().defaultNow(),
});

export const verification = pgTable("verification", {
  id: text("id").primaryKey(),
  identifier: text("identifier").notNull(),
  value: text("value").notNull(),
  expiresAt: timestamp("expiresAt").notNull(),
  createdAt: timestamp("createdAt"),
  updatedAt: timestamp("updatedAt"),
});

Now create the database instance with Encore:

// auth/db.ts
import { SQLDatabase } from "encore.dev/storage/sqldb";
import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import * as schema from "./schema";

export const DB = new SQLDatabase("auth", {
  migrations: "./migrations",
});

// Create Drizzle instance
const pool = new Pool({
  connectionString: DB.connectionString,
});

export const db = drizzle(pool, { schema });

Note: We're using Encore's SQL migration files instead of Drizzle Kit's migration tools. Encore handles applying migrations across all environments and integrates with the deployment pipeline, while Drizzle gives us type-safe queries.

The authentication system requires database tables for users, sessions, accounts, and verification tokens. Encore uses SQL migration files to define your database schema, which are automatically applied when your application starts. Create the initial migration file with the required BetterAuth tables:

-- auth/migrations/1_create_auth_tables.up.sql
CREATE TABLE IF NOT EXISTS "user" (
    "id" TEXT PRIMARY KEY NOT NULL,
    "name" TEXT NOT NULL,
    "email" TEXT NOT NULL UNIQUE,
    "emailVerified" BOOLEAN NOT NULL DEFAULT false,
    "image" TEXT,
    "createdAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "updatedAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS "session" (
    "id" TEXT PRIMARY KEY NOT NULL,
    "expiresAt" TIMESTAMP NOT NULL,
    "token" TEXT NOT NULL UNIQUE,
    "createdAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "updatedAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "ipAddress" TEXT,
    "userAgent" TEXT,
    "userId" TEXT NOT NULL REFERENCES "user"("id") ON DELETE CASCADE
);

CREATE TABLE IF NOT EXISTS "account" (
    "id" TEXT PRIMARY KEY NOT NULL,
    "accountId" TEXT NOT NULL,
    "providerId" TEXT NOT NULL,
    "userId" TEXT NOT NULL REFERENCES "user"("id") ON DELETE CASCADE,
    "accessToken" TEXT,
    "refreshToken" TEXT,
    "idToken" TEXT,
    "accessTokenExpiresAt" TIMESTAMP,
    "refreshTokenExpiresAt" TIMESTAMP,
    "scope" TEXT,
    "password" TEXT,
    "createdAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "updatedAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS "verification" (
    "id" TEXT PRIMARY KEY NOT NULL,
    "identifier" TEXT NOT NULL,
    "value" TEXT NOT NULL,
    "expiresAt" TIMESTAMP NOT NULL,
    "createdAt" TIMESTAMP,
    "updatedAt" TIMESTAMP
);

Creating the auth service

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

export default new Service("auth");

Configuring BetterAuth

Now we'll configure BetterAuth to use our PostgreSQL database. We'll create a connection pool using the pg package and pass it to BetterAuth. Encore's SQLDatabase provides a connectionString that we can use. We'll also use Encore's secrets management to securely store the authentication secret key:

// auth/better-auth.ts
import { betterAuth } from "better-auth";
import { Pool } from "pg";
import { DB } from "./db";
import { secret } from "encore.dev/config";

// Secrets let you store sensitive values like API keys securely
// Learn more: https://encore.dev/docs/ts/primitives/secrets
const authSecret = secret("BetterAuthSecret");

// Create a PostgreSQL pool for BetterAuth
const pool = new Pool({
  connectionString: DB.connectionString,
});

// Create BetterAuth instance with database connection
export const auth = betterAuth({
  database: pool,
  secret: authSecret(),
  emailAndPassword: {
    enabled: true,
    requireEmailVerification: false, // Set to true in production
  },
  session: {
    expiresIn: 60 * 60 * 24 * 7, // 7 days
    updateAge: 60 * 60 * 24, // Update session every 24 hours
  },
});

Set your auth secret using Encore's CLI (learn more about secrets management). You'll be prompted to enter the secret value securely:

# Set the secret for local development
encore secret set --dev BetterAuthSecret

# For production environments
encore secret set --prod BetterAuthSecret

Tip: Generate a strong random secret using openssl rand -base64 32 or a password manager.

Implementing authentication endpoints

With the configuration in place, let's build the API endpoints that handle user registration, login, and logout. In Encore, endpoints are defined using the api function with TypeScript interfaces for request and response validation, providing automatic request parsing, validation, and API documentation:

// auth/auth.ts
import { api } from "encore.dev/api";
import { auth } from "./better-auth";
import log from "encore.dev/log";

// Register a new user
interface SignUpRequest {
  email: string;
  password: string;
  name: string;
}

interface AuthResponse {
  user: {
    id: string;
    email: string;
    name: string;
  };
  session: {
    token: string;
    expiresAt: Date;
  };
}

export const signUp = api(
  { expose: true, method: "POST", path: "/auth/signup" },
  async (req: SignUpRequest): Promise<AuthResponse> => {
    log.info("User signup attempt", { email: req.email });

    // Use BetterAuth to create user
    const result = await auth.api.signUpEmail({
      body: {
        email: req.email,
        password: req.password,
        name: req.name,
      },
    });

    if (!result.user || !result.token) {
      throw new Error("Failed to create user");
    }

    return {
      user: {
        id: result.user.id,
        email: result.user.email,
        name: result.user.name,
      },
      session: {
        token: result.token,
        expiresAt: new Date(Date.now() + 60 * 60 * 24 * 7 * 1000), // 7 days from now
      },
    };
  }
);

// Login existing user
interface SignInRequest {
  email: string;
  password: string;
}

export const signIn = api(
  { expose: true, method: "POST", path: "/auth/signin" },
  async (req: SignInRequest): Promise<AuthResponse> => {
    log.info("User signin attempt", { email: req.email });

    const result = await auth.api.signInEmail({
      body: {
        email: req.email,
        password: req.password,
      },
    });

    if (!result.user || !result.token) {
      throw new Error("Invalid credentials");
    }

    return {
      user: {
        id: result.user.id,
        email: result.user.email,
        name: result.user.name,
      },
      session: {
        token: result.token,
        expiresAt: new Date(Date.now() + 60 * 60 * 24 * 7 * 1000), // 7 days from now
      },
    };
  }
);

// Logout user
interface SignOutRequest {
  token: string;
}

export const signOut = api(
  { expose: true, method: "POST", path: "/auth/signout" },
  async (req: SignOutRequest): Promise<{ success: boolean }> => {
    await auth.api.signOut({
      body: { token: req.token },
    });

    return { success: true };
  }
);

Creating the auth handler

To protect endpoints and enable authentication across your application, we need to create an auth handler. The auth handler is a special function that Encore calls automatically for any incoming request containing authentication parameters (like an Authorization header). It verifies session tokens and makes authenticated user data available to protected endpoints.

Note on session validation: BetterAuth's built-in session management (auth.api.getSession()) is designed for cookie-based authentication in web browsers. For REST API bearer tokens, we validate sessions by querying the database directly. This approach is standard for API authentication and gives us full control over the validation logic while still leveraging BetterAuth for the security-critical parts (password hashing, user creation, and session storage).

// auth/handler.ts
import { APIError, Gateway, Header } from "encore.dev/api";
import { authHandler } from "encore.dev/auth";
import { db } from "./db";
import { session, user } from "./schema";
import { eq } from "drizzle-orm";
import log from "encore.dev/log";

// Define what we extract from the Authorization header
interface AuthParams {
  authorization: Header<"Authorization">;
}

// Define what authenticated data we make available to endpoints
interface AuthData {
  userID: string;
  email: string;
  name: string;
}

const myAuthHandler = authHandler(
  async (params: AuthParams): Promise<AuthData> => {
    const token = params.authorization.replace("Bearer ", "");

    if (!token) {
      throw APIError.unauthenticated("no token provided");
    }

    try {
      // Query the session directly from the database using Drizzle
      // BetterAuth's getSession() is designed for cookie-based web apps,
      // so for REST API bearer tokens we validate by querying the session table
      const sessionRows = await db
        .select({
          userId: session.userId,
          expiresAt: session.expiresAt,
        })
        .from(session)
        .where(eq(session.token, token))
        .limit(1);

      const sessionRow = sessionRows[0];

      if (!sessionRow) {
        throw APIError.unauthenticated("invalid session");
      }

      // Check if session is expired
      if (new Date(sessionRow.expiresAt) < new Date()) {
        throw APIError.unauthenticated("session expired");
      }

      // Get user info
      const userRows = await db
        .select({
          id: user.id,
          email: user.email,
          name: user.name,
        })
        .from(user)
        .where(eq(user.id, sessionRow.userId))
        .limit(1);

      const userRow = userRows[0];

      if (!userRow) {
        throw APIError.unauthenticated("user not found");
      }

      return {
        userID: userRow.id,
        email: userRow.email,
        name: userRow.name,
      };
    } catch (e) {
      log.error(e);
      throw APIError.unauthenticated("invalid token", e as Error);
    }
  }
);

// Create gateway with auth handler
export const gateway = new Gateway({ authHandler: myAuthHandler });

Creating protected endpoints

Let's build a profile service to demonstrate how authentication works with protected endpoints. Any endpoint marked with auth: true will automatically require authentication, and you can access the authenticated user's information using the getAuthData() function throughout your application:

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

export default new Service("profile");

// profile/profile.ts
import { api } from "encore.dev/api";
import { getAuthData } from "~encore/auth";
import log from "encore.dev/log";

interface UserProfile {
  id: string;
  email: string;
  name: string;
}

export const getProfile = api(
  {
    expose: true,
    auth: true, // Requires authentication
    method: "GET",
    path: "/profile",
  },
  async (): Promise<UserProfile> => {
    // Get authenticated user data from auth handler
    const authData = getAuthData()!;

    log.info("Profile accessed", { userID: authData.userID });

    return {
      id: authData.userID,
      email: authData.email,
      name: authData.name,
    };
  }
);

interface UpdateProfileRequest {
  name: string;
}

export const updateProfile = api(
  {
    expose: true,
    auth: true,
    method: "PUT",
    path: "/profile",
  },
  async (req: UpdateProfileRequest): Promise<UserProfile> => {
    const authData = getAuthData()!;

    log.info("Profile update", {
      userID: authData.userID,
      newName: req.name,
    });

    // In a real app, update the database here
    // For now, just return the updated data
    return {
      id: authData.userID,
      email: authData.email,
      name: req.name,
    };
  }
);

Testing the backend

Start your Encore backend using the built-in development server (make sure Docker is running first):

encore run

Your API is now running locally with hot-reloading enabled. Encore automatically starts the PostgreSQL database in a Docker container and runs all migrations. Open the local development dashboard at http://localhost:9400 to explore your API with interactive documentation, view distributed traces for each request, and test endpoints directly in the browser.

Exploring the database: The local development dashboard includes a built-in database explorer powered by Drizzle Studio. You can browse your database tables, view user records and sessions, and run queries visually - perfect for debugging and understanding how BetterAuth stores authentication data.

Testing with curl

Sign up a new user:

curl -X POST http://localhost:4000/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!",
    "name": "John Doe"
  }'

You'll get a response with a session token:

{
  "user": {
    "id": "...",
    "email": "user@example.com",
    "name": "John Doe"
  },
  "session": {
    "token": "eyJhbGci...",
    "expiresAt": "2025-01-23T..."
  }
}

Sign in:

curl -X POST http://localhost:4000/auth/signin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!"
  }'

Access protected endpoint:

curl http://localhost:4000/profile \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Update profile:

curl -X PUT http://localhost:4000/profile \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe"}'

Every request generates a detailed trace that shows the complete execution flow. Here's what a trace looks like for the update profile request, showing the auth handler validation, database query, and response:

Using the API Explorer

Open the local development dashboard at http://localhost:9400 and you'll see Encore's built-in development tools:

Service Catalog: All your API endpoints with auto-generated documentation
Request/Response Schemas: Type-safe interfaces automatically extracted from your code
API Testing: Test endpoints directly in the browser with a built-in API client
Distributed Tracing: Visual timeline of each request showing database queries, service calls, and auth handler execution
Authentication Status: See which endpoints require authentication and test them with bearer tokens

Try signing up a user through the API Explorer or curl, then use the returned session token to access the protected /profile endpoint. You'll see the full request trace, including the auth handler execution and database queries.

Connecting to a frontend

One of Encore's most powerful features is its ability to automatically generate type-safe API clients for your frontend. This ensures that your frontend and backend stay in sync with zero manual work. Generate the client for your frontend application:

encore gen client frontend/src/lib/client.ts

This creates a fully typed TypeScript client that matches your backend API exactly. Here's how to use it in your frontend application:

import Client, { Local } from "./lib/client";

// Sign up
const client = new Client(Local);
const { user, session } = await client.auth.signUp({
  email: "user@example.com",
  password: "SecurePass123!",
  name: "John Doe",
});

// Store session token (e.g., in localStorage or a cookie)
localStorage.setItem("authToken", session.token);

// Make authenticated requests
const authedClient = new Client(Local, {
  auth: { authorization: `Bearer ${session.token}` },
});

const profile = await authedClient.profile.getProfile();

CORS Configuration:

When your frontend runs on a different origin (like localhost:5173 for Vite or localhost:3000 for Next.js), you need to configure CORS to allow authenticated requests. Update the encore.app file in your project root:

{
  "id": "auth-app",
  "global_cors": {
    "allow_origins_with_credentials": ["http://localhost:5173"]
  }
}

This tells Encore to accept authenticated requests from your frontend's origin. In production, Encore automatically configures CORS based on your deployment settings.

For complete frontend integration guides, see the frontend integration documentation.

Deployment

Deploying your authentication backend with Encore is straightforward. Simply push your code:

git add .
git commit -m "Add BetterAuth authentication"
git push encore

Before your production deployment can run, set the production authentication secret:

# Generate a strong random secret for production
encore secret set --prod BetterAuthSecret

Note: Encore Cloud is great for prototyping and development with fair use limits (100k requests/day, 1GB database). For production workloads, you can connect your AWS or GCP account and Encore will provision and deploy infrastructure directly in your cloud account.

Advanced features

Adding OAuth providers

BetterAuth supports social login with popular OAuth providers like Google, GitHub, Discord, and many more. Here's how to add Google OAuth authentication to your backend:

// auth/better-auth.ts
import { betterAuth } from "better-auth";

const googleClientId = secret("GoogleClientId");
const googleClientSecret = secret("GoogleClientSecret");

export const auth = betterAuth({
  database: {
    provider: "postgres",
    url: DB.connectionString,
  },
  secret: authSecret(),
  emailAndPassword: {
    enabled: true,
  },
  socialProviders: {
    google: {
      clientId: googleClientId(),
      clientSecret: googleClientSecret(),
      redirectURI: "http://localhost:4000/auth/callback/google",
    },
  },
});

Email verification

For production applications, you'll want to verify user email addresses before allowing them to access your application. Enable email verification in your BetterAuth configuration and integrate with an email service like Resend, SendGrid, or Amazon SES:

export const auth = betterAuth({
  // ... other config
  emailAndPassword: {
    enabled: true,
    requireEmailVerification: true,
  },
  emailVerification: {
    sendVerificationEmail: async (user, url) => {
      // Send email with verification link
      // Integrate with Resend, SendGrid, etc.
    },
  },
});

Two-factor authentication

Enhance your application's security by adding two-factor authentication (2FA). BetterAuth provides a plugin system that makes it easy to add TOTP-based 2FA using authenticator apps like Google Authenticator or Authy:

import { twoFactor } from "better-auth/plugins";

export const auth = betterAuth({
  // ... other config
  plugins: [
    twoFactor({
      issuer: "YourApp",
    }),
  ],
});

Session management

Give your users visibility and control over their active sessions by adding endpoints to list and revoke sessions. This is especially important for security-conscious applications where users might want to sign out of all devices:

export const listSessions = api(
  { expose: true, auth: true, method: "GET", path: "/sessions" },
  async () => {
    const authData = getAuthData()!;

    // Query sessions from database
    const sessions = await DB.query`
      SELECT id, created_at, ip_address, user_agent
      FROM session
      WHERE user_id = ${authData.userID}
      ORDER BY created_at DESC
    `;

    return { sessions: Array.from(sessions) };
  }
);

export const revokeSession = api(
  { expose: true, auth: true, method: "DELETE", path: "/sessions/:id" },
  async ({ id }: { id: string }) => {
    await auth.api.signOut({ body: { sessionId: id } });
    return { success: true };
  }
);

Next steps

Now that you have a fully functional authentication backend, here are some ways to extend and enhance it:

Add role-based access control (RBAC) by extending the auth data with user roles and permissions, then check roles in your endpoints
Implement email verification with services like Resend or SendGrid to confirm user email addresses
Add OAuth providers (Google, GitHub, Discord, etc.) for social login to improve user experience
Enable two-factor authentication (2FA) for enhanced security using BetterAuth's 2FA plugin
Add password reset functionality with secure email links and token expiration
Implement organizations and teams using BetterAuth's organization plugin for B2B applications
Add session management features to let users view and revoke active sessions from different devices
Integrate with Pub/Sub to send welcome emails asynchronously when users sign up using Encore's Pub/Sub primitive
Add API rate limiting to protect your auth endpoints from brute force attacks
Implement refresh tokens for longer-lived authentication sessions

Conclusion

You've successfully built a complete, production-ready authentication backend with BetterAuth and Encore.ts! This combination gives you the best of both worlds:

BetterAuth handles the security-critical aspects of authentication (password hashing, session management, token generation, and OAuth integration) so you don't have to worry about implementing these complex features from scratch.

Encore.ts provides the infrastructure foundation with type-safe APIs, automatic database provisioning, built-in secrets management, and seamless deployment. The auth handler pattern makes it trivial to protect any endpoint with a simple auth: true flag, while getAuthData() gives you type-safe access to authenticated user information throughout your application.

The auto-generated TypeScript client ensures complete type safety between your frontend and backend, catching errors at compile time rather than runtime. The local development dashboard provides full observability into authentication flows with distributed tracing, making debugging authentication issues straightforward.

Ready to learn more?

Check out the Encore documentation to explore more features like Pub/Sub, Cron Jobs, and Object Storage
Browse the example applications to see real-world implementations
Join our Discord community to get help, share what you're building, and connect with other developers
Read the BetterAuth documentation to explore advanced authentication features

Join the OSS Hackathon 2025 and win $10k+ in prizes

Ivan Cernja — Fri, 25 Jul 2025 08:50:53 +0000

Too many essential tools are locked behind paywalls or simply unavailable as open source alternatives. The Open Source Hackathon 2025 (September 1-7) is our attempt to grow the ecosystem of open source alternatives and reward builders who create them.

🏆 Prizes

First Place (Choose One):

Herman Miller Aeron Chair
Bambulab P1S 3D Printer
Framework Laptop 13
Plus Leap credits

Second Place (Choose One):

Walkingpad C2
Teenage Engineering OB-4
Steam Deck OLED
Plus Leap credits

Third Place (Choose One):

Airpods Pro 2
Keychron Q1 Pro
Sony WH-1000XM5
Plus Leap credits

🚀 The Challenge: Build Open Source Alternatives

Build something real. Make it open source. Win prizes. Help others break free from vendor lock-in.

We're looking for applications that provide open alternatives to tools currently:

Behind paywalls
Limited by restrictive licenses
Missing open source equivalents

💻 Why Build with Leap?

Leap is an AI-powered development platform that builds full-stack applications with real backend services, APIs, and deploys to your AWS or GCP cloud — all from a single prompt. It's built on top of Encore, our open source backend framework.

It's never been easier or faster to build open source alternatives, which makes this hackathon the perfect opportunity to create something meaningful.

📅 Key Details

Dates: September 1-7, 2025
Format: Remote & async, individual participation
Prize Pool: $10k+ in prizes
Partner: Polar.sh
Registration: osshackathon.com

👥 Join the Community

100+ developers have already signed up! More details will be coming soon.

Questions? Reach out to hello@leap.new

We take privacy seriously and will only use your email for hackathon-related updates. Full stop.