Backend Development with Encore.ts

Overview

This skill provides comprehensive guidance for building production-ready backend applications using Encore.ts, a TypeScript backend framework that provides type-safe APIs, automatic infrastructure provisioning, and built-in best practices for distributed systems.

Core Capabilities

This skill covers all aspects of backend development with Encore.ts:

1. API Development

• •Type-safe REST API endpoints
• •Request/response validation
• •Raw endpoints for custom HTTP handling
• •Streaming APIs via WebSocket
• •Static asset serving
• •GraphQL support

2. Database Management

• •PostgreSQL database integration
• •Migration management
• •Type-safe query execution
• •ORM support (Drizzle, Prisma)

3. Authentication & Authorization

• •Custom auth handlers
• •Token validation (JWT, API keys, sessions)
• •Auth data propagation
• •Protected endpoints

4. Asynchronous Messaging

• •Pub/Sub topics and subscriptions
• •Event-driven architecture
• •Delivery guarantees (at-least-once, exactly-once)
• •Ordered message delivery

5. Storage & Caching

• •Object storage (S3-compatible)
• •File upload/download
• •Public/private buckets
• •Caching strategies

6. Scheduled Tasks

• •Cron jobs with periodic or cron expression schedules
• •Background task execution
• •Automated maintenance tasks

7. Middleware & CORS

• •Request/response middleware
• •Cross-origin resource sharing configuration
• •Custom header handling

8. Logging & Monitoring

• •Structured logging
• •Application metadata access
• •Environment-based configuration
• •Performance monitoring

9. Configuration Management

• •Secret management
• •Environment-specific configuration
• •Feature flags

10. Application Architecture

• •Service organization
• •Monorepo structure
• •Microservices patterns
• •Service-to-service communication

When to Use This Skill

Use this skill when:

• •Creating new Encore.ts backend services
• •Implementing API endpoints (REST, streaming, or GraphQL)
• •Setting up database schemas and migrations
• •Implementing authentication or authorization
• •Building event-driven architectures with Pub/Sub
• •Managing file storage or implementing caching
• •Scheduling background jobs or periodic tasks
• •Configuring middleware or CORS policies
• •Managing secrets and environment configuration
• •Structuring large-scale backend applications

Quick Start Guide

Creating a New Service

Define a service using encore.service.ts:

import { Service } from "encore.dev/service";
export default new Service("my-service");

Creating an API Endpoint

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

interface HelloRequest {
  name: string;
}

interface HelloResponse {
  message: string;
}

export const hello = api(
  { method: "POST", expose: true },
  async (req: HelloRequest): Promise<HelloResponse> => {
    return { message: `Hello, ${req.name}!` };
  }
);

Setting Up a Database

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

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

// Create migration: migrations/001_initial.up.sql

Querying the Database

// Fetch multiple rows
const users = await db.query`SELECT * FROM users`;
for await (const user of users) {
  console.log(user.name);
}

// Fetch single row
const user = await db.queryRow`SELECT * FROM users WHERE id = ${userId}`;

// Execute insert/update
await db.exec`INSERT INTO users (name, email) VALUES (${name}, ${email})`;

Working with Detailed References

This skill includes comprehensive reference documentation in the references/ directory. Load these references when working on specific features:

API Development

Reference: references/api-endpoints.md

Load when:

• •Creating new endpoints
• •Implementing validation
• •Adding streaming support
• •Setting up raw endpoints
• •Handling API errors

Database Operations

Reference: references/databases.md

Load when:

• •Setting up databases
• •Creating migrations
• •Writing queries
• •Integrating ORMs
• •Troubleshooting database issues

Authentication

Reference: references/authentication.md

Load when:

• •Implementing auth handlers
• •Adding protected endpoints
• •Working with JWT, API keys, or sessions
• •Managing auth data propagation

Pub/Sub Messaging

Reference: references/pubsub-messaging.md

Load when:

• •Setting up event-driven architecture
• •Creating topics and subscriptions
• •Implementing message handlers
• •Configuring delivery guarantees

Storage & Caching

Reference: references/storage-caching.md

Load when:

• •Implementing file uploads/downloads
• •Setting up object storage buckets
• •Implementing caching strategies
• •Managing public/private assets

Application Structure

Reference: references/app-structure-services.md

Load when:

• •Organizing multi-service applications
• •Setting up monorepo structure
• •Planning service boundaries
• •Implementing service-to-service calls

Cron Jobs

Reference: references/cron-jobs-scheduling.md

Load when:

• •Scheduling periodic tasks
• •Creating background jobs
• •Setting up automated maintenance
• •Implementing complex schedules

Logging & Monitoring

Reference: references/logging-monitoring.md

Load when:

• •Implementing logging strategies
• •Accessing application metadata
• •Setting up environment-based behavior
• •Monitoring application performance

Middleware & CORS

Reference: references/middleware-cors.md

Load when:

• •Creating request/response middleware
• •Configuring CORS policies
• •Implementing rate limiting
• •Adding custom headers

Secrets & Configuration

Reference: references/secrets-config.md

Load when:

• •Managing API keys and secrets
• •Setting up environment configuration
• •Implementing feature flags
• •Rotating credentials

Development Workflow

1. Initial Setup

Create an Encore.ts application:

encore app create my-app
cd my-app

2. Define Service Structure

Start with single service for new projects:

my-app/
├── encore.app
├── package.json
├── encore.service.ts
├── api.ts
└── migrations/

3. Run Locally

encore run

Access local development dashboard at http://localhost:9400

4. Test Endpoints

# Using curl
curl http://localhost:4000/endpoint-name -X POST -d '{"key":"value"}'

# Or use the Encore Dev Dashboard

5. Apply Database Migrations

Migrations run automatically on encore run. View database:

# Open psql shell
encore db shell database-name

# Get connection string
encore db conn-uri database-name

6. Deploy

# Push to git (triggers automatic deployment if connected to Encore Cloud)
git push

# Or manually deploy
encore deploy

Common Patterns

Building a REST API

1. •Define service: Create encore.service.ts
2. •Create endpoints: Define API handlers in api.ts
3. •Add validation: Use TypeScript interfaces for request/response
4. •Handle errors: Use APIError for consistent error responses
5. •Test locally: Use encore run and test endpoints

Setting Up Authentication

1. •Create auth handler: Implement authHandler in auth service
2. •Configure gateway: Link auth handler to Gateway
3. •Protect endpoints: Add auth: true to endpoint options
4. •Access auth data: Use getAuthData() in protected endpoints

Building Event-Driven Architecture

1. •Define topics: Create Topic instances for events
2. •Publish events: Call topic.publish() when events occur
3. •Create subscriptions: Define Subscription instances with handlers
4. •Ensure idempotency: Make handlers safe for duplicate delivery

Implementing Background Jobs

1. •Create cron job: Use CronJob with schedule
2. •Define endpoint: Create API endpoint for job logic
3. •Handle failures: Implement error handling and logging
4. •Test manually: Call endpoint directly during development

Best Practices

Code Organization

• •Start with single service, split when boundaries are clear
• •Use shared modules for common types and utilities
• •Keep services focused on single responsibility
• •Document service APIs with comments explaining why each exists

Database Management

• •Always use parameterized queries (template literals)
• •Keep migrations sequential and atomic
• •Test migrations locally before deploying
• •Use transactions for multi-step operations

Error Handling

• •Use APIError for consistent error responses
• •Log errors with context for debugging
• •Provide clear error messages to clients
• •Handle edge cases explicitly

Security

• •Never commit secrets to version control
• •Use auth handlers for protected endpoints
• •Validate all user input
• •Implement rate limiting for public endpoints
• •Use HTTPS in production

Performance

• •Implement caching for expensive operations
• •Use database indexes for common queries
• •Monitor endpoint response times
• •Implement pagination for large result sets

Testing

• •Test endpoints manually during development
• •Write unit tests for business logic
• •Test error conditions
• •Verify authentication and authorization

CLI Commands Reference

Running Application

encore run              # Run locally with live reload
encore run --debug      # Run with debug logging

Database Operations

encore db shell <db-name>        # Open psql shell
encore db conn-uri <db-name>     # Get connection string
encore db reset [service-name]   # Reset database

Secrets Management

encore secret set --type prod <secret-name>    # Set production secret
encore secret list                             # List all secrets

Logs

encore logs                    # Stream local logs
encore logs --env=prod         # Stream production logs
encore logs --json             # JSON formatted logs

Code Generation

encore gen client <app-id> --lang=typescript    # Generate API client

Troubleshooting

Common Issues

Issue: Database connection errors

• •Solution: Check connection string, verify database exists, check migrations

Issue: Authentication not working

• •Solution: Verify auth handler is linked to Gateway, check auth data structure

Issue: CORS errors in browser

• •Solution: Configure global_cors in encore.app file

Issue: Pub/Sub messages not delivered

• •Solution: Check subscription handler, verify topic name, check error logs

Issue: Secrets not found

• •Solution: Set secrets using CLI or dashboard, check environment type

Getting Help

• •Read detailed reference documentation in references/ directory
• •Check Encore.ts documentation: https://encore.dev/docs
• •View example applications: https://github.com/encoredev/examples
• •Use encore --help for CLI usage

Example Applications

Reference these example repositories for complete implementations:

• •Hello World: https://github.com/encoredev/examples/tree/main/ts/hello-world
• •URL Shortener: https://github.com/encoredev/examples/tree/main/ts/url-shortener
• •Uptime Monitor: https://github.com/encoredev/examples/tree/main/ts/uptime

Resources

All detailed documentation is available in the references/ directory:

• •api-endpoints.md - Complete API development reference
• •databases.md - Database and migration guide
• •authentication.md - Auth implementation patterns
• •pubsub-messaging.md - Event-driven architecture
• •storage-caching.md - File storage and caching
• •app-structure-services.md - Application organization
• •cron-jobs-scheduling.md - Background task scheduling
• •logging-monitoring.md - Logging and observability
• •middleware-cors.md - Middleware and CORS config
• •secrets-config.md - Secret and config management

Load specific references as needed when working on related features.