Labsco
encoredev logo

encore-service

★ 25

by encoredev · part of encoredev/skills

Structures an Encore.ts app into services: how to lay out one service, several services, or groups of related services, and how they call each other over the network instead of importing code directly.

🔥🔥🔥✓ VerifiedFreeQuick setup
🧩 One of 28 skills in the encoredev/skills package — works on its own, and pairs well with its siblings.

WHEN YOUR AGENT SHOULD USE IT

A QUICK BOUNDARY

USE FOR

  • Add a new service to an existing Encore.ts application.
  • Call an endpoint in another service instead of importing its code directly.
  • Group a large application's many services into logical systems, like commerce or identity.
  • Give a service its own dedicated database inside one Encore.ts app.

DO NOT USE FOR

  • Deciding where the boundaries between services should be in the first place.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

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

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:

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

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
  • 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