Encore Service Structure

Instructions

Creating a Service

Every Encore service needs an encore.service.ts file:

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

export default new Service("my-service");

Minimal Service Structure

my-service/
├── encore.service.ts    # Service definition (required)
├── api.ts               # API endpoints
└── db.ts                # Database (if needed)

Application Patterns

Single Service (Recommended Start)

Best for new projects - start simple, split later if needed:

my-app/
├── package.json
├── encore.app
├── encore.service.ts
├── api.ts
├── db.ts
└── migrations/
    └── 001_initial.up.sql

Multi-Service

For distributed systems with clear domain boundaries:

my-app/
├── encore.app
├── package.json
├── user/
│   ├── encore.service.ts
│   ├── api.ts
│   └── db.ts
├── order/
│   ├── encore.service.ts
│   ├── api.ts
│   └── db.ts
└── notification/
    ├── encore.service.ts
    └── api.ts

Large Application (System-based)

Group related services into systems:

my-app/
├── encore.app
├── commerce/
│   ├── order/
│   │   └── encore.service.ts
│   ├── cart/
│   │   └── encore.service.ts
│   └── payment/
│       └── encore.service.ts
├── identity/
│   ├── user/
│   │   └── encore.service.ts
│   └── auth/
│       └── encore.service.ts
└── comms/
    ├── email/
    │   └── encore.service.ts
    └── push/
        └── encore.service.ts

Service-to-Service Calls

Import other services from ~encore/clients:

import { user } from "~encore/clients";

export const getOrderWithUser = api(
  { method: "GET", path: "/orders/:id", expose: true },
  async ({ id }): Promise<OrderWithUser> => {
    const order = await getOrder(id);
    const orderUser = await user.get({ id: order.userId });
    return { ...order, user: orderUser };
  }
);

When to Split Services

Split when you have:

Signal	Action
Different scaling needs	Split (e.g., auth vs analytics)
Different deployment cycles	Split
Clear domain boundaries	Split
Shared database tables	Keep together
Tightly coupled logic	Keep together
Just organizing code	Use folders, not services

Service with Middleware

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

const loggingMiddleware = middleware(
  { target: { all: true } },
  async (req, next) => {
    console.log(`Request: ${req.requestMeta?.path}`);
    return next(req);
  }
);

export default new Service("my-service", {
  middlewares: [loggingMiddleware],
});

Guidelines

• Services cannot be nested within other services
• Start with one service, split when there's a clear reason
• Use ~encore/clients for cross-service calls (never direct imports)
• Each service can have its own database
• Service names should be lowercase, descriptive
• Don't create services just for code organization - use folders instead