service

Encore Service Structure

Instructions

Before creating any files, confirm that the project is an Encore.ts project and that an encore.app file exists. Confirm the target directory with the user before creating encore.service.ts or db.ts files or migrations, especially at the application root.

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

A service can be defined at the application root:

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

Multi-Service

Each service lives in its own directory:

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. The api helper used below must also be imported from the Encore API package:

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

This example shows only the call pattern. The order lookup helper and the combined result type are placeholders to define in your own service. For any endpoint exposed publicly, require authentication, check that the caller owns the requested order, and return only the user fields the caller needs rather than the full user record. Give the id parameter an explicit type and validate it, return a not found error when the order is missing, and run the ownership check before calling the other service.

Guidelines

• Services cannot be nested within other services
• Use ~encore/clients for cross-service calls (never direct imports)
• Each service can have its own database
• Require authentication and access checks on exposed endpoints before returning user or order data
• Service names should be lowercase, descriptive
• Don't create services just for code organization - use folders instead
• Use encore-architecture when the service boundaries have not been decided