Labsco
encoredev logo

encore-go-service

★ 25

by encoredev · part of encoredev/skills

How an Encore Go app gets split into separate services: any folder with an endpoint in it becomes one, and calling another service reads like calling an ordinary function.

🔥🔥🔥✓ 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

  • Turn a single package into a service just by adding one API endpoint to it.
  • Split a growing app into separate service packages like user, order, and notification.
  • Call another service's function directly and let Encore turn it into an RPC.
  • Group related services under a shared folder once an app gets large.

DO NOT USE FOR

  • Deciding where service boundaries should go is a separate skill's job, not this one.

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.go Service Structure

Instructions

In Encore.go, each package with an API endpoint is automatically a service. No special configuration needed.

Creating a Service

Simply create a package with at least one //encore:api endpoint:

// user/user.go
package user

import "context"

type User struct {
    ID    string `json:"id"`
    Email string `json:"email"`
    Name  string `json:"name"`
}

//encore:api public method=GET path=/users/:id
func GetUser(ctx context.Context, params *GetUserParams) (*User, error) {
    // This makes "user" a service
}

Minimal Service Structure

user/
├── user.go          # API endpoints
├── db.go            # Database (if needed)
└── migrations/      # SQL migrations
    └── 1_create_users.up.sql

Application Patterns

Single Service

An application can define its APIs in one root service package:

my-app/
├── encore.app
├── go.mod
├── api.go           # All endpoints
├── db.go            # Database
└── migrations/
    └── 1_initial.up.sql

Multi-Service

Each service lives in its own package:

my-app/
├── encore.app
├── go.mod
├── user/
│   ├── user.go
│   ├── db.go
│   └── migrations/
├── order/
│   ├── order.go
│   ├── db.go
│   └── migrations/
└── notification/
    └── notification.go

Large Application (System-based)

Group related services into systems:

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

Service-to-Service Calls

Just import and call the function directly - Encore handles the RPC:

package order

import (
    "context"
    "encore.app/user"  // Import the user service
)

//encore:api auth method=GET path=/orders/:id
func GetOrderWithUser(ctx context.Context, params *GetOrderParams) (*OrderWithUser, error) {
    order, err := getOrder(ctx, params.ID)
    if err != nil {
        return nil, err
    }
    
    // This becomes an RPC call - Encore handles it
    orderUser, err := user.GetUser(ctx, &user.GetUserParams{ID: order.UserID})
    if err != nil {
        return nil, err
    }
    
    return &OrderWithUser{Order: order, User: orderUser}, nil
}

Internal Helpers (Non-Service Packages)

Create packages without //encore:api endpoints for shared code:

my-app/
├── user/
│   └── user.go       # Service (has API)
├── order/
│   └── order.go      # Service (has API)
└── internal/
    ├── util/
    │   └── util.go   # Not a service (no API)
    └── validation/
        └── validate.go

Guidelines

  • A package becomes a service when it has //encore:api endpoints
  • Services cannot be nested within other services
  • Cross-service calls look like regular function calls
  • Each service can have its own database
  • Package names should be lowercase, descriptive
  • Don't create services just for code organization - use sub-packages instead
  • Use encore-architecture when the service boundaries have not been decided