DEV Community: Encore

Build a production-ready SaaS app (that will scale!)

Marcus Kohlberg — Mon, 09 Feb 2026 13:42:15 +0000

Thinking of building a SaaS application? This starter template will help you create a scalable and production ready application using Encore.ts and Next.js.

It uses Clerk for authentication, has a Stripe integration for payments, and uses Tailwind and shadcn/ui for styling and components.

Demo: https://encorets-saas-starter.vercel.app
Open on GitHub

Features

Marketing landing page (/)
Pricing page (/pricing) which connects to Stripe Checkout
Dashboard pages with (/dashboard)
Subscription management (/dashboard/subscription)

Tech stack

Backend framework: Encore.ts
Frontend framework: Next.js
Authentication: Clerk
Payments: Stripe
UI Library: Tailwind & shadcn/ui

Getting started

Install or Update Encore

Install Encore:

macOS: brew install encoredev/tap/encore
Linux: curl -L https://encore.dev/install.sh | bash
Windows: iwr https://encore.dev/install.ps1 | iex

Note: This starter requires Encore v1.46.9+, if you have an older version installed, update using encore version update.

Create app

Create a local app from this template:

encore app create my-app-name --example=ts/saas-starter

Then install the frontend dependencies:

cd my-app-name/frontend
pnpm install

Setting up Clerk

Create a Clerk account if you haven't already. Then, in the Clerk dashboard, create a new application.

Ensure the application is configured to support organizations, which can be enabled on the Organization management settings page.

Secrets

If you host your app on Vercel (see deployment instructions further down), you can connect your Clerk application with your Vercel project under Integrations in the project settings on Vercel.
Don't forget to run vercel env pull afterward.

Otherwise, go to the API Keys page for your app. Copy the "Publishable Key" and one of the "Secret keys". To your frontend project, add them to the .env.local as

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY={PUBLISHABLE_KEY}
CLERK_SECRET_KEY={SECRET_KEY}

You also need to add the following environment variables to your frontend project:

NEXT_PUBLIC_CLERK_SIGN_IN_URL="/sign-in"

To add them to Encore, go to the API Keys page for your app. Copy the "Publishable Key" and one of the "Secret keys".

From your terminal (inside the backend directory), run:

$ encore secret set --prod ClerkSecretKey

Next, do the same for the development secret. The most secure way is to create another secret key (Clerk allows you to have multiple).
Once you have a client secret for development, set it similarly to before:

$ encore secret set --dev ClerkSecretKey

Setting up Stripe

Create a Stripe account if you don't have one already. Then, create your account and make sure to set up the products and pricing plans. You must also configure the billing customer portal.

You will also need to add your backend as a webhook endpoint in Stripe and set the endpoint URL to https://YOUR_DOMAIN/stripe/webhook.

Currently, the pricing plans are stored in frontend/lib/plans.ts, but you can also read them from Stripe or store them in a database if you prefer.

Secrets

On the Stripe dashboard, go to the Developers page and create a new API key. Copy the "Secret Key".

From your terminal (inside the backend directory), run:

$ encore secret set --dev StripeSecretKey

To be able to verify the incoming webhook requests, you need to copy the signing secret from the Webhook page on the Stripe dashboard and add it to Encore by running:

$ encore secret set --dev StripeWebhookSigningSecret

Once you want to set it up for production, create a separate Secret key and Webhook Signing Secret for production and run:

$ encore secret set --prod StripeSecretKey
$ encore secret set --prod StripeWebhookSigningSecret

Testing payments

To test Stripe payments, use the following test card details:

Card Number: 4242 4242 4242 4242
Expiration: Any future date
CVC: Any 3-digit number

Vercel Environment Variables

Vercel-specific environment variables are not set on local by default, so you need to add them yourself. This can be done on the project settings page on Vercel.

Please add the following environment variables for development:

VERCEL_ENV="development"
NEXT_PUBLIC_VERCEL_ENV="development"
VERCEL_GIT_PULL_REQUEST_ID=""
NEXT_PUBLIC_VERCEL_GIT_PULL_REQUEST_ID=""

Run locally

Run your Encore backend:

cd backend
encore run

Note: This will fail unless you set up the Stripe and Clerk secrets according to the instructions above.

In a different terminal window, run the React frontend using Next.js:

cd frontend
pnpm run dev

Generating a request client

Keep the contract between the backend and frontend in sync by regenerating the request client whenever you make a change to an Encore endpoint.

pnpm run gen # Deployed Encore staging environment
# or
pnpm run gen:local # Locally running Encore backend

Deployment

Encore

Deploy your backend to a staging environment in Encore's free development cloud:

git add -A .
git commit -m 'Commit message'
git push encore

Then head over to the Cloud Dashboard to monitor your deployment and find your production URL.

From there you can also see metrics, traces, connect your app to a GitHub repo to get automatic deploys on new commits, and connect your own AWS or GCP account to use for deployment.

Nice job, your SaaS backend is now deployed to the cloud!

Next.js on Vercel

Create a repo and push the project to GitHub.
Create a new project on Vercel and point it to your GitHub repo.
Select frontend as the root directory for the Vercel project.

Frontend & CORS configuration

The backend needs to know where the frontend is hosted, in order to serve the correct redirect URLs
back from Stripe. It is also necessary for CORS to work correctly.

To handle this, you need to update two configuration files.

First, update the FRONTEND_URL constant in backend/config.ts to point to where your frontend is hosted.

Secondly, if you are running into CORS issues when calling your Encore API from your frontend then you may need to specify which origins are allowed to access your API (via browsers). You do this by specifying the global_cors key in the encore.app file, which has the following structure:

"global_cors": {
  // allow_origins_without_credentials specifies the allowed origins for requests
  // that don't include credentials. If nil it defaults to allowing all domains
  // (equivalent to ["*"]).
  "allow_origins_without_credentials": [
    "<ORIGIN-GOES-HERE>"
  ],

  // allow_origins_with_credentials specifies the allowed origins for requests
  // that include credentials. If a request is made from an Origin in this list
  // Encore responds with Access-Control-Allow-Origin: <Origin>.
  //
  // The URLs in this list may include wildcards (e.g. "https://*.example.com"
  // or "https://*-myapp.example.com").
  "allow_origins_with_credentials": [
    "<DOMAIN-GOES-HERE>"
  ]
}

Both of these default to "https://encorets-saas-starter.vercel.app" which is the hosted demo application.

More information on CORS configuration can be found here: https://encore.dev/docs/ts/develop/cors

Wrapping up

You now have a scalable and production-ready SaaS application up and running. Now keep going and develop your SaaS product!

If you have questions: Join our Discord
Star Encore on GitHub
Find more Open-source App Examples
Join our Squad if you want to contribute content to Encore's blog

The End of Heroku: What It Means for Your Apps

Marcus Kohlberg — Mon, 09 Feb 2026 13:39:47 +0000

Heroku recently moved to a "sustaining engineering model." No new features, no new enterprise contracts. The platform stays running for existing customers, but active development has stopped.

Heroku launched in 2007 and was acquired by Salesforce for $212 million in 2010. After removing its free tier in November 2022 and years of slowing feature development, the February 2026 announcement made the trajectory official.

For teams planning a move, the biggest shift is toward infrastructure ownership: deploying to your own AWS or GCP account rather than renting another managed platform. But there are several directions and here's what each option offers.

Encore Cloud

If you want to replicate Heroku's git push workflow while owning your infrastructure, Encore Cloud provisions managed resources in your own AWS or GCP account (powered by Encore, an open-source framework with 11k+ GitHub stars). You declare infrastructure as type-safe objects in your TypeScript or Go code, and Encore provisions the corresponding managed services. Everything else is standard TypeScript or Go.

import { SQLDatabase } from "encore.dev/storage/sqldb";
import { Topic } from "encore.dev/pubsub";
import { CronJob } from "encore.dev/cron";

// These declarations are all Encore needs to provision your infrastructure.
// Everything else in your codebase is standard TypeScript (or Go).
const db = new SQLDatabase("main", { migrations: "./migrations" });
const events = new Topic<OrderEvent>("events", { deliveryGuarantee: "at-least-once" });
const _ = new CronJob("daily-cleanup", { schedule: "0 0 * * *", endpoint: cleanup });

On AWS, this provisions RDS, SNS/SQS, and CloudWatch Events. On GCP, it provisions Cloud SQL, Pub/Sub, and Cloud Scheduler. Networking, IAM, encryption, and backups are configured automatically following cloud provider best practices.

Deployment works like Heroku: git push encore main. The infrastructure runs in your account, visible in the AWS or GCP console. Local development runs everything with encore run, every pull request gets an automatic preview environment, and built-in distributed tracing and metrics come included.

For teams using AI agents like Cursor and Claude Code, infrastructure-from-code means infrastructure doesn't drift from application logic. When AI changes your code, infrastructure updates automatically to match, and guardrails like type validation and compile-time checks are built in so there's no separate Terraform or YAML falling out of sync.

Companies like Groupon already use this at scale with TypeScript and Go, deploying to both AWS and GCP (Azure is not yet supported).

Managed Platforms

Render

Render is the most direct Heroku replacement. The concepts are nearly identical: git-push deploys, managed Postgres, background workers, cron jobs. If you want the smallest possible change from your current workflow, Render is the shortest path.

The mental model carries over cleanly as you connect a Git repo, define services in render.yaml or through the dashboard, and push to deploy. Render handles SSL, load balancing, and auto-deploys from your branch, and preview environments work similarly to Heroku Review Apps.

The main tradeoff is that you're still on someone else's infrastructure. If Render changes direction, raises prices, or gets acquired, you're in a similar position to where you are with Heroku. Per-service and per-seat pricing can also add up for larger teams running multiple services.

Fly.io

Fly.io takes a different approach. Instead of abstracting away infrastructure, it gives you lightweight VMs (Machines) in 30+ regions worldwide. The deployment workflow has a similar feel (fly deploy and your app is live) but the underlying model is closer to running containers than Heroku-style dynos.

Fly.io is well-suited for applications where latency matters, with fast cold starts, automatic placement near users, and a global Anycast network. The community is active and the team is responsive on support.

The managed Postgres offering has had some reliability challenges, though the team is actively improving this with their new MPG product. Pricing is usage-based, which can make monthly bills harder to predict compared to Heroku's flat per-dyno model.

Railway

Railway focuses on modern developer experience. The dashboard is clean, deploys are fast, and the project model is intuitive. It supports any language via Docker or Nixpacks (similar to Heroku buildpacks) and deploys from GitHub, a CLI, or templates.

Railway stands out for teams: paid plans include unlimited seats, which is a meaningful differentiator over Render and Heroku where each team member adds to the bill. Support for monorepos and multi-service projects is solid.

Like Render and Fly.io, you're on Railway's infrastructure. It's a managed platform with the same category of tradeoffs around ownership and portability.

Self-Hosted: Coolify, Dokku, Dokploy

Tools like Coolify, Dokku, and Dokploy run a Heroku-like experience on your own VPS. The typical setup is a Hetzner or DigitalOcean server with one of these tools installed. You get git-push deploys, automatic SSL, and database provisioning.

This path gives you the most control at the lowest price. Dokku is the most mature option (built in 2013, supports Heroku buildpacks directly). Coolify and Dokploy offer web dashboards for teams that prefer a GUI.

The tradeoff is operational responsibility. You manage the server: OS updates, security patches, backups, monitoring. For side projects and internal tools this is fine. For production applications that need high availability, it takes significantly more effort.

How to Choose

If you need...	Consider
Infrastructure ownership, compliance	Encore Cloud (your AWS/GCP)
Fastest migration from Heroku	Render
Global edge performance	Fly.io
Modern DX, unlimited team seats	Railway
Lowest possible cost	Self-hosted (Coolify/Dokku)

Heroku's concepts (dynos, Postgres, worker processes, config vars, pipelines) map cleanly to every alternative. The migration is more about choosing the right destination than dealing with technical complexity.

For step-by-step migration guides:

Related Resources

How to Deploy to AWS in 2026

Marcus Kohlberg — Tue, 27 Jan 2026 09:26:40 +0000

Deploying to AWS in 2026 looks different than it did five years ago. The ecosystem has matured, new tools have emerged, and the "right" approach depends more than ever on your team's size, experience, and what you're building.

This guide covers the main options for deploying backend applications to AWS, from clicking around in the console to fully automated infrastructure-as-code. We'll look at the trade-offs, show code examples, and help you pick the right approach.

Option 1: AWS Console (Click-Ops)

The AWS Console is where most developers start. You log in, click through wizards, and configure services manually.

When it works:

Learning AWS concepts
Quick experiments and prototypes
One-off tasks that don't need to be repeatable

When it doesn't:

Anything you need to reproduce (staging, production, disaster recovery)
Team environments where multiple people need to understand the setup
Compliance requirements that need audit trails

The console is fine for learning, but you'll quickly hit limits. There's no version control, no way to review changes, and no easy path to reproduce what you built. Most teams graduate to something else within months.

Option 2: Infrastructure from Code (Encore)

Encore takes a different approach than traditional infrastructure-as-code. Instead of writing separate infrastructure definitions, you declare what your application needs directly in your backend code. Encore Cloud then provisions AWS resources automatically.

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

// This creates an RDS PostgreSQL database
const db = new SQLDatabase("users", {
  migrations: "./migrations",
});

// This creates SNS/SQS
const signups = new Topic<SignupEvent>("signups", {
  deliveryGuarantee: "at-least-once",
});

// This creates a Fargate service or Lambda
export const createUser = api(
  { method: "POST", path: "/users", expose: true },
  async (req: CreateUserRequest) => {
    const user = await db.exec`INSERT INTO users ...`;
    await signups.publish({ userId: user.id });
    return user;
  }
);

When you push code, Encore analyzes it and provisions the corresponding AWS resources: RDS for databases, SNS/SQS for Pub/Sub, Fargate or Lambda for compute, S3 for object storage, CloudWatch for cron jobs.

What you get:

No Terraform, CloudFormation, or YAML to write
Infrastructure changes through code review (not manual config)
Local development with Docker-based versions of AWS services
Preview environments for every pull request
Built-in observability (tracing, metrics, logs)

Trade-offs:

Less granular control over resource configuration than raw Terraform
Newer ecosystem than Terraform

Encore works well for teams that want AWS infrastructure ownership without becoming infrastructure experts. Companies like Groupon use this approach to power their backends at scale. The open-source framework has 11k+ GitHub stars.

Option 3: AWS CloudFormation

CloudFormation is AWS's native infrastructure-as-code service. You define resources in YAML or JSON templates, and CloudFormation creates and manages them.

AWSTemplateFormatVersion: '2010-09-09'
Resources:
  MyDatabase:
    Type: AWS::RDS::DBInstance
    Properties:
      DBInstanceClass: db.t3.micro
      Engine: postgres
      MasterUsername: admin
      MasterUserPassword: !Ref DBPassword
      AllocatedStorage: 20

  MyLambda:
    Type: AWS::Lambda::Function
    Properties:
      Runtime: nodejs18.x
      Handler: index.handler
      Code:
        S3Bucket: my-deployment-bucket
        S3Key: lambda.zip

What you get:

Native AWS integration, no third-party dependencies
Drift detection (CloudFormation can tell if someone changed resources manually)
Stack management for grouping related resources

Trade-offs:

Verbose YAML/JSON syntax
Slow feedback loops (deployments can take minutes)
Limited programming constructs (no loops, limited conditionals)
AWS-only (can't manage GCP or other providers)

CloudFormation is reliable but painful to write. Most teams either use a wrapper (like CDK) or switch to Terraform.

Option 4: AWS CDK

The Cloud Development Kit (CDK) lets you write CloudFormation in real programming languages. You write TypeScript, Python, or Go, and CDK synthesizes CloudFormation templates.

import * as cdk from 'aws-cdk-lib';
import * as rds from 'aws-cdk-lib/aws-rds';
import * as lambda from 'aws-cdk-lib/aws-lambda';

export class MyStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string) {
    super(scope, id);

    const database = new rds.DatabaseInstance(this, 'Database', {
      engine: rds.DatabaseInstanceEngine.postgres({
        version: rds.PostgresEngineVersion.VER_15,
      }),
      instanceType: ec2.InstanceType.of(
        ec2.InstanceClass.T3, 
        ec2.InstanceSize.MICRO
      ),
    });

    const fn = new lambda.Function(this, 'Handler', {
      runtime: lambda.Runtime.NODEJS_18_X,
      handler: 'index.handler',
      code: lambda.Code.fromAsset('lambda'),
      environment: {
        DATABASE_URL: database.instanceEndpoint.hostname,
      },
    });
  }
}

What you get:

Real programming language instead of YAML
IDE autocomplete and type checking
Reusable constructs and abstractions
Still generates CloudFormation under the hood

Trade-offs:

Adds a compilation step (CDK → CloudFormation → AWS)
Debugging means understanding both CDK and CloudFormation
AWS-only
Still requires understanding AWS service configuration

CDK is a significant improvement over raw CloudFormation, but you still need to understand AWS services deeply.

Option 5: Terraform

Terraform is the industry standard for infrastructure-as-code. It uses HashiCorp Configuration Language (HCL) and works across AWS, GCP, Azure, and hundreds of other providers.

// Terraform HCL syntax
provider "aws" {
  region = "us-east-1"
}

resource "aws_db_instance" "main" {
  identifier        = "my-database"
  engine            = "postgres"
  engine_version    = "15"
  instance_class    = "db.t3.micro"
  allocated_storage = 20
  username          = "admin"
  password          = var.db_password
}

resource "aws_lambda_function" "api" {
  function_name = "my-api"
  runtime       = "nodejs18.x"
  handler       = "index.handler"
  filename      = "lambda.zip"

  environment {
    variables = {
      DATABASE_URL = aws_db_instance.main.endpoint
    }
  }
}

What you get:

Multi-cloud support
Massive ecosystem (providers for everything)
State management for tracking what's deployed
Plan/apply workflow for reviewing changes before deploying
Large community and extensive documentation

Trade-offs:

Learning HCL (it's not hard, but it's another language)
State file management (remote state, locking, etc.)
Can get complex for large infrastructures
Separate from your application code

The trade-off is that you're maintaining two codebases: your application and your infrastructure. This adds overhead but gives you more control over individual resource settings.

Option 6: Pulumi

Pulumi is like Terraform but uses real programming languages instead of HCL. You write TypeScript, Python, Go, or C# to define infrastructure.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const database = new aws.rds.Instance("database", {
  engine: "postgres",
  engineVersion: "15",
  instanceClass: "db.t3.micro",
  allocatedStorage: 20,
  username: "admin",
  password: config.requireSecret("dbPassword"),
});

const fn = new aws.lambda.Function("api", {
  runtime: "nodejs18.x",
  handler: "index.handler",
  code: new pulumi.asset.FileArchive("./lambda"),
  environment: {
    variables: {
      DATABASE_URL: database.endpoint,
    },
  },
});

What you get:

Real programming language (loops, conditionals, functions)
Type safety and IDE support
Multi-cloud support
Can share code between infrastructure and application

Trade-offs:

Smaller ecosystem than Terraform
Still requires understanding cloud service configuration
Separate from your application code

Pulumi offers an alternative to Terraform's HCL syntax if you prefer using TypeScript or Python for infrastructure definitions.

Option 7: SST (Serverless Stack)

SST focuses on serverless AWS deployments. It's built on CDK but optimized for Lambda, API Gateway, and related services.

import { Api, Table } from "sst/constructs";

export function API({ stack }: StackContext) {
  const table = new Table(stack, "users", {
    fields: { id: "string", email: "string" },
    primaryIndex: { partitionKey: "id" },
  });

  const api = new Api(stack, "api", {
    routes: {
      "POST /users": "packages/functions/src/create.handler",
    },
  });

  api.bind([table]);

  return { api };
}

What you get:

Optimized for serverless (Lambda, DynamoDB, etc.)
Live Lambda development (code changes without redeploy)
Good developer experience for serverless patterns

Trade-offs:

Serverless-focused (less suited for containers or traditional servers)
Built on CDK, so inherits some of its complexity
AWS-only

SST targets serverless applications on AWS. It's built on CDK, so you'll still need to understand AWS concepts.

Comparison

Approach	Learning Curve	Flexibility	Maintenance	Best For
Console	Low	High	None (not repeatable)	Learning, experiments
Encore	Low	Medium	Low	Teams wanting AWS without DevOps
CloudFormation	High	High	High	AWS-native shops
CDK	Medium	High	Medium	Teams comfortable with AWS
Terraform	Medium	Very High	Medium	Multi-cloud, large infra
Pulumi	Medium	Very High	Medium	Developers who prefer real code
SST	Low-Medium	Medium	Low	Serverless applications

Which Should You Choose?

Choose the Console if:

You're learning AWS
It's a one-time experiment

Choose Encore if:

You want to focus on backend code, not infrastructure
You want AWS ownership without becoming an AWS expert
You value fast iteration and built-in observability
Your infrastructure needs are covered by databases, queues, cron, storage

Choose CloudFormation/CDK if:

You're already invested in the AWS ecosystem
You need fine-grained control over every AWS setting
Your organization mandates AWS-native tooling

Choose Terraform if:

You need multi-cloud support
You have complex infrastructure requirements
Your team has (or wants to build) infrastructure expertise
You need to manage non-AWS resources

Choose Pulumi if:

You want Terraform's flexibility with real programming languages
Your team prefers TypeScript/Python over HCL

Choose SST if:

You're building serverless applications
You want the best Lambda development experience
You're okay being AWS-only

Getting Started

Most teams should start with the simplest option that meets their needs, then evolve if necessary. If you're building a backend application and don't want to become an infrastructure expert, Encore is worth trying. If you need maximum flexibility or multi-cloud support, Terraform is the industry standard.

Whatever you choose, avoid the console for anything you need to reproduce. Infrastructure-as-code isn't optional in 2026—it's how professional teams ship software.

Related Resources

Best TypeScript Backend Frameworks in 2026

Marcus Kohlberg — Fri, 23 Jan 2026 14:42:24 +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 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.

Moving on from Terraform CDK

Marcus Kohlberg — Tue, 13 Jan 2026 09:06:02 +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.

Encore Cloud 2.0 - Development Platform for the AI Era

Marcus Kohlberg — Tue, 16 Dec 2025 15:43:50 +0000

We started Encore five years ago because developers were spending too much time configuring infrastructure and jumping through hoops, not building products.

That problem persists. AI agents can now scaffold entire backends in minutes, but running them well - with proper observability, and reliable, secure, infrastructure across multiple environments - still requires significant work.

Today, we're launching Encore Cloud 2.0, a big upgrade to our development platform that understands your code and automates the operations layer.

The problem

Before we get into what's new, we'd like to take a moment to expand on why we set out building Encore. I mean, what exactly is wrong with existing tools like Terraform?

These days, AI is already helpful in writing Terraform. But its potential usefulness is limited, because it lacks context.

For most teams, the "truth" of a system is scattered. Business logic lives in one place, infrastructure definitions in another, permissions somewhere else, plus there's those pesky yet inevitable manual changes in cloud consoles. There's no single authoritative model of how the system runs.

Without such a model, common questions require significant human effort to get right:

Which services actually need to talk?
What permissions are truly required?
How can we be sure this infra change won't break something?

Fragmentation turns operating your system into a game of "spot the difference" between your intent and your infrastructure.

Framework-defined infrastructure

We designed Encore to solve this by ensuring that the application code is the single source of truth for everything that impacts application behavior, so that we can derive a complete system model from it.

It works by providing an open source backend framework for TypeScript and Go, which comes with packages to define services and APIs, and infrastructure like databases, message queues, and scheduled jobs.

Unlike Terraform, you do not define specific cloud resources, configurations, or providers in code. You only express what is relevant to the application behavior.

In Encore.ts, creating a database object is new SQLDatabase("users"). An API endpoint is a function with the api() decorator. This is enough for Encore to understand what you're building, identify which services need which permissions, and generate everything needed to run it.

From your code, Encore Cloud automatically orchestrates:

Cloud Resources: Databases, caches, and queues
IAM Policies: Least-privilege permissions, generated automatically
Networking: Service discovery and secure connectivity
Observability: Tracing and metrics, wired out of the box
Documentation: Service catalog, API docs, and architecture diagrams

Because infrastructure details are not embedded in your code, the same application can run on different environments without modification. You create an environment with Encore Cloud and choose where it runs, on AWS or Google Cloud, and using what type of infrastructure, Kubernetes or serverless platforms.

Everything deploys to your own AWS or Google Cloud account by integrating directly with their APIs. Encore provisions resources with sane defaults, which you can tune in Encore Cloud or directly in your cloud provider without them being overridden.

With this approach, there's an intentional tradeoff; you partially give up having low-level control over individual cloud resources defined in code, in exchange for productivity, portability, and safety at the system level.

For teams that want to hand-tune every single resource, Terraform is likely the right tool. For teams that want to focus on application behavior and evolve infrastructure over time without rewrites, Encore optimizes for that path while providing easy-to-reach knobs and configuration options for key things.

Because your code is the source of truth, drift is effectively eliminated. If infrastructure is missing, Encore provisions it. If a resource is removed from your code, Encore marks it as "unused" so you can safely delete it when you're ready.

— But, what about lock-in? We're engineers ourselves and get why this matters, so we've designed Encore to reduce lock-in from the start. Learn more about migrating away

What's new in 2.0

Now let's get to the exciting bit, what's new.

Encore Cloud 2.0 builds on the foundation we've created over the past five years, and delivers an upgraded platform that feels less like "managing servers" and more like shipping product.

1. A redesigned operations dashboard

We've rebuilt the dashboard to reflect how engineers actually think about systems. It allows you to navigate large distributed applications across multiple environments, surfacing topology, deployments, and infrastructure state without the noise.

2. Full-stack observability

For teams using Encore.ts, metrics now live alongside traces and logs. You get a complete, correlated view of system behavior across services. No external agents to install, no dashboards to configure manually.

For teams using Encore.go where metrics was already available, you get an upgraded dashboard with more performant and usable graphs.

3. System transparency

Because Encore understands your system model, it maintains the artifacts that usually go stale. In this release we've improved the performance and usability of these tools:

Architecture Diagrams: Always up-to-date, generated from the live graph.
Service Catalog: A real-time inventory of what's running.
Local MCP Server: Allowing AI agents to inspect your system, and take actions like call endpoints, view traces, and more.

4. Zero-friction onboarding

We've streamlined the path from "new repo" to "production URL." With tighter GitHub integration, you can go from code to a fully provisioned cloud environment in minutes.

Jump in

Encore Cloud 2.0 is available now.

Deploy an example app to a free development environment, or book a demo to see how it works with a production system.

For teams already using Encore, the 2.0 dashboard features are rolling out automatically. Update to the latest CLI version using encore version update to start using metrics in Encore.ts.

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

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

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');

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`;

Local development environment with database running

A Complete API Example

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}
    `;
  }
);

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

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})
    `;
  },
});

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

Infrastructure changes require approval before provisioning

Type Safety

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}`;
  }
);

Local Development

Automatic service flow visualization and architecture diagram

Working with Existing Infrastructure

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

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

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.

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

Encore's MCP Server lets your AI tools introspect your app

Marcus Kohlberg — Thu, 22 May 2025 08:49:34 +0000

Large Language Models (LLMs) are becoming more powerful, but without context, they're limited in how much they can do. The Model Context Protocol (MCP) is a new open standard for how applications provide context to LLMs.

Starting in Encore v1.47.0, an MCP server is available for all Encore applications. You run it locally with encore mcp start, which makes your app accessible to any MCP-compatible tool, such as Claude Desktop, IDEs like Cursor, or other AI-powered assistants.

The MCP Server enables AI tools to deeply introspect your application to understand its architecture, APIs, infrastructure, and runtime data in a structured way.

This means AI tools can more accurately generate code, validate changes, and help with other development tasks like debugging.

Example

With the MCP Server, you can now ask Cursor's agent mode to perform advanced actions, such as:

"Add an endpoint that publishes to a pub/sub topic, call it and verify that the publish is in the traces"

Cursor's agent will implement the feature, look up any unfamiliar conventions in Encore's documentation, start the local application to call the API, and use the MCP Server to fetch and analyze traces.

Want to try it? It's all open-source, try it yourself by installing Encore.

Other uses

There are many ways you can leverage the MCP server to improve your workflow when using AI development tools:

1. Higher-quality agentic code generation

With structured access to your app's APIs, services, infrastructure, and traces, AI can generate code that’s better aligned with your architecture and implementation patterns.

2. Context-aware design suggestions

Need to add a new service or refactor an existing one? With visibility into your app’s architecture and infrastructure, AI can propose changes that respect system boundaries and dependencies.

3. Faster debugging with trace and infra context

When debugging, AI can use local trace data, database schemas, to help you pinpoint issues and suggest relevant fixes, all based on the actual behavior of your local app. It can also call endpoints directly and help you understand the results by interpreting the corresponding traces.

How it works

Encore understands your application by using static analysis. This is a fancy term for parsing and analyzing the code you write, to create a graph of how your application works.
This graph closely represents your own mental model of the system: boxes and arrows that represent systems and services that communicate with other systems, pass data and connect to infrastructure. We call it the Encore Application Model.

Encore's MCP server exposes "tools" that are built on top of this model, to enable LLMs to understand your application's structure, retrieve relevant information, and take actions within your system.

In this first release, the following tools are exposed via the MCP Server:

Database Tools

get_databases: Retrieve metadata about all SQL databases defined in the application, including their schema, tables, and relationships.
query_database: Execute SQL queries against one or more databases in the application.

API Tools

call_endpoint: Make HTTP requests to any API endpoint in the application.
get_services: Retrieve comprehensive information about all services and their endpoints in the application.
get_middleware: Retrieve detailed information about all middleware components in the application.
get_auth_handlers: Retrieve information about all authentication handlers in the application.

Trace Tools

get_traces: Retrieve a list of request traces from the application, including their timing, status, and associated metadata.
get_trace_spans: Retrieve detailed information about one or more traces, including all spans, timing information, and associated metadata.

Source Code Tools

get_metadata: Retrieve the complete application metadata, including service definitions, database schemas, API endpoints, and other infrastructure components.
get_src_files: Retrieve the contents of one or more source files from the application.

PubSub Tools

get_pubsub: Retrieve detailed information about all PubSub topics and their subscriptions in the application.

Storage Tools

get_storage_buckets: Retrieve comprehensive information about all storage buckets in the application.
get_objects: List and retrieve metadata about objects stored in one or more storage buckets.

Cache Tools

get_cache_keyspaces: Retrieve comprehensive information about all cache keyspaces in the application.

Metrics Tools

get_metrics: Retrieve comprehensive information about all metrics defined in the application.

Cron Tools

get_cronjobs: Retrieve detailed information about all scheduled cron jobs in the application.

Secret Tools

get_secrets: Retrieve metadata about all secrets used in the application.

Documentation Tools

search_docs: Search the Encore documentation using Algolia's search engine.
get_docs: Retrieve the full content of specific documentation pages.

Learn more in the docs

Example: Integrating with Cursor

Cursor is one of the most popular AI-powered IDE's, and it's simple to use Encore's MCP server together with Cursor.

Just create the file .cursor/mcp.json with the following settings:

{
    "mcpServers": {
        "encore-mcp": {
            "command": "encore",
            "args": ["mcp", "run", "--app=your-app-id"]
        }
    }
}

Learn more in Cursor's MCP docs

It's early days

This is just an initial release and we think we're only scratching the surface of what's possible when giving AI tools the capability to deeply and accurately understand your applications.

We think there's a lot more to do in this space, but we're now confident that building applications on top of a declarative framework, like Encore, is a foundational and powerful enabler as AI tooling matures.

Want to try it? It's all open-source, try it yourself by installing Encore.