Encore Go

https://encore.dev/docs/go
Admin
Encore.go is a backend framework for distributed systems that provides a declarative approach to...
Tokens:82,145
Snippets:1,010
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Start the frontend

Source: https://encore.dev/docs/go/tutorials/meeting-notes

Install dependencies and launch the frontend development server in a separate terminal.

```shell
$ cd you-app-name/frontend
$ npm install
$ npm run dev
```

--------------------------------

### Install Connect tools

Source: https://encore.dev/docs/go/how-to/grpc-connect

Install the necessary CLI tools for working with Protobuf and Connect.

```shell
$ go install github.com/bufbuild/buf/cmd/buf@latest
$ go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
$ go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
$ go install connectrpc.com/connect/cmd/protoc-gen-connect-go@latest
```

--------------------------------

### Create application from example repository

Source: https://encore.dev/docs/go/tutorials/incident-management-tool

Initialize a new project by cloning the example on-call application repository.

```shell
$ encore app create --example https://github.com/encoredev/example-app-oncall
```

--------------------------------

### Create Encore application from example

Source: https://encore.dev/docs/go/tutorials/booking-system

Initializes a new project using the specified starting-point branch.

```shell
$ encore app create booking-system --example=github.com/encoredev/example-booking-system/tree/starting-point
```

--------------------------------

### Install sqlc

Source: https://encore.dev/docs/go/tutorials/booking-system

Install the sqlc CLI tool to generate Go code from SQL queries.

```shell
$ go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest
```

--------------------------------

### Install Authentication Dependencies

Source: https://encore.dev/docs/go/how-to/logto-auth

Install the required JWT and JWKS packages for Go.

```shell
$ go get github.com/golang-jwt/jwt/v5
$ go get github.com/MicahParks/keyfunc/v3
```

--------------------------------

### Create an Encore application

Source: https://encore.dev/docs/go/tutorials/meeting-notes

Initialize a new project using the meeting-notes example template.

```shell
$ encore app create my-app --example=meeting-notes
```

--------------------------------

### Run the backend locally

Source: https://encore.dev/docs/go/tutorials/meeting-notes

Navigate to the project directory and start the Encore development environment.

```shell
$ cd you-app-name # replace with the app name you picked
$ encore run
```

--------------------------------

### Install GORM dependencies

Source: https://encore.dev/docs/go/how-to/atlas-gorm

Install the necessary GORM packages and the Postgres driver.

```shell
go get -u gorm.io/gorm gorm.io/driver/postgres
```

--------------------------------

### Run application

Source: https://encore.dev/docs/go/cli/cli-reference

Starts the local development environment with optional flags for debugging, port configuration, and live-reloading.

```shell
$ encore run [--debug] [--watch=true] [--port=<number>] [--listen=<addr>] [flags]
```

--------------------------------

### encore mcp start

Source: https://encore.dev/docs/go/cli/mcp

Starts an SSE-based MCP server and displays connection information.

```APIDOC
## encore mcp start

### Description
Starts an SSE-based MCP server and displays connection information.

### Usage
`encore mcp start [--app=<app-id>]`
```

--------------------------------

### Registering and starting the outbox relay

Source: https://encore.dev/docs/go/how-to/pubsub-outbox

Initialize the relay with a storage backend, register the topic, and start the polling process during service initialization.

```go
-- user/service.go --
package user

import (
	"context"
	
    "encore.dev/pubsub"
    "encore.dev/storage/sqldb"
    "x.encore.dev/infra/pubsub/outbox"
)

type Service struct {
	signupsRef pubsub.Publisher[*SignupEvent]
}

// db is the database the outbox table is stored in
var db = sqldb.NewDatabase(...)

// Create the SignupsTopic somehow.
var SignupsTopic = pubsub.NewTopic[*SignupEvent](/* ... */)

func initService() (*Service, error) {
    // Initialize the relay to poll from our database.
	relay := outbox.NewRelay(outbox.SQLDBStore(db))
	
	// Register the SignupsTopic to be polled.
    signupsRef := pubsub.TopicRef[pubsub.Publisher[*SignupEvent]](SignupsTopic)
	outbox.RegisterTopic(relay, signupsRef)
	
	// Start polling.
	go relay.PollForMessage(context.Background(), -1)
	
	return &Service{signupsRef: signupsRef}, nil
}
```

--------------------------------

### Install Clerk SDK

Source: https://encore.dev/docs/go/how-to/clerk-auth

Install the required Clerk Go module in your Encore project.

```shell
$ go get github.com/clerkinc/clerk-sdk-go/clerk
```

--------------------------------

### Install Firebase dependencies

Source: https://encore.dev/docs/go/how-to/firebase-auth

Run this command to install the necessary Firebase and syncutil modules for your project.

```shell
$ go get firebase.google.com/go/v4 go4.org/syncutil
```

--------------------------------

### Install Auth0 dependencies

Source: https://encore.dev/docs/go/how-to/auth0-auth

Install the required OIDC and OAuth2 modules for your Encore project.

```shell
$ go get github.com/coreos/go-oidc/v3/oidc golang.org/x/oauth2
```

--------------------------------

### Run the Encore service

Source: https://encore.dev/docs/go/how-to/grpc-connect

Starts the local development server for the Encore project.

```shell
$ encore run
```

--------------------------------

### Install Delve

Source: https://encore.dev/docs/go/how-to/debug

Install the Delve debugger using the Go toolchain.

```shell
$ go install github.com/go-delve/delve/cmd/dlv@latest
```

--------------------------------

### Start an SSE-based MCP server

Source: https://encore.dev/docs/go/cli/mcp

Starts an SSE-based MCP server and displays connection information.

```shell
$ encore mcp start [--app=<app-id>]
```

--------------------------------

### Start Encore Application

Source: https://encore.dev/docs/go/observability/dev-dash

Run the application locally to launch the development dashboard and view the API base URL.

```bash
$ encore run
API Base URL:      http://localhost:4000
Dev Dashboard URL: http://localhost:9400/hello-world-cgu2
```

--------------------------------

### Infrastructure configuration JSON schema example

Source: https://encore.dev/docs/go/self-host/configure-infra

A sample configuration file defining metadata, SQL servers, service discovery, Redis, metrics, and other infrastructure settings.

```json
{
  "$schema": "https://encore.dev/schemas/infra.schema.json",
  "metadata": {
    "app_id": "my-app",
    "env_name": "my-env",
    "env_type": "production",
    "cloud": "gcp",
    "base_url": "https://my-app.com"
  },
  "sql_servers": [
    {
      "host": "my-db-host:5432",
      "databases": {
        "my-db": {
          "username": "my-db-owner",
          "password": {"$env": "DB_PASSWORD"}
        }
      }
    }
  ],
  "service_discovery": {
    "myservice": {
      "base_url": "https://myservice:8044"
    }
  },
  "redis": {
    "my-redis": {
      "database_index": 0,
      "auth": {
        "type": "acl",
        "username": "encoreredis",
        "password": {"$env": "REDIS_PASSWORD"}
      },
      "host": "my-redis-host",
    }
  },
  "metrics": {
    "type": "prometheus",
    "remote_write_url": "https://my-remote-write-url"
  },
  "graceful_shutdown": {
    "total": 30
  },
  "auth": [
    {
      "type": "key",
      "id": 1,
      "key": {"$env": "SVC_TO_SVC_KEY"}
    }
  ],
  "secrets": {
    "AppSecret": {"$env": "APP_SECRET"}
  },
  "pubsub": [
    {
      "type": "gcp_pubsub",
      "project_id": "my-project",
      "topics": {
        "my-topic": {
          "name": "gcp-topic-name",
          "subscriptions": {
            "encore-subscription": {
              "name": "gcp-subscription-name"
            }
          }
        }
      }
    }
  ],
  "object_storage": [
    {
      "type": "gcs",
      "buckets": {
          "my-gcs-bucket": {
            "name": "my-gcs-bucket",
          }
        }
    }
  ]
}
```

--------------------------------

### Define CUE configuration files

Source: https://encore.dev/docs/go/develop/config

Example of generated metadata and custom configuration logic using CUE files.

```cue
-- mysvc/encore.gen.cue --
// Code generated by encore. DO NOT EDIT.
package mysvc

#Meta: {
	APIBaseURL: string
	Environment: {
		Name:  string
		Type:  "production" | "development" | "ephemeral" | "test"
		Cloud: "aws" | "gcp" | "encore" | "local"
	}
}

#Config: {
	ReadOnly: bool   // Put the system into read-only mode
    Example:  string
}
#Config
-- mysvc/myconfig.cue --
// Set example to "hello world"
Example: "hello world"

// By default we're not in read only mode
ReadOnly: bool | *false

// But on the old production environment, we're in read only mode
if #Meta.Environment.Name == "old-prod" {
    ReadOnly: true
}
```

--------------------------------

### Start the Encore MCP Server

Source: https://encore.dev/docs/go/ai-integration

Run this command from the root of your Encore application directory to initialize the MCP server.

```bash
encore mcp start
```

--------------------------------

### Example Directory Structure for Encore Systems

Source: https://encore.dev/docs/go/primitives/app-structure

A visual representation of how to organize services into system-specific sub-directories within an Encore project.

```text
/my-trello-clone
├── encore.app                  // ... and other top-level project files
│
├── trello                      // trello system (a directory)
│   ├── board                   // board service (a Go package)
│   │   └── board.go            // board service code
│   └── card                    // card service (a Go package)
│       └── card.go             // card service code
│
├── premium                     // premium system (a directory)
│   ├── payment                 // payment service (a Go package)
│   │   └── payment.go          // payment service code
│   └── subscription            // subscription service (a Go package)
│       └── subscription.go     // subscription service code
│
└── usr                         // usr system (a directory)
    ├── org                     // org service (a Go package)
    │   └── org.go              // org service code
    └── user                    // user service (a Go package)
        └── user.go             // user service code
```

--------------------------------

### Project Directory Structure

Source: https://encore.dev/docs/go/primitives/app-structure

Example of a standard Encore project layout with multiple services and database migrations.

```text
/my-app
├── encore.app                       // ... and other top-level project files
│
├── hello                            // hello service (a Go package)
│   ├── migrations                   // hello service db migration (directory)
│   │   └── 1_create_table.up.sql    // hello service db migration
│   ├── hello.go                     // hello service code
│   └── hello_test.go                // tests for hello service
│
└── world                            // world service (a Go package)
    └── world.go                     // world service code
```

--------------------------------

### Representing service structure on disk

Source: https://encore.dev/docs/go/primitives/services

Example directory layout showing how Go packages function as distinct services within an Encore application.

```text
/my-app
├── encore.app          // ... and other top-level project files
│
├── hello               // hello service (a Go package)
│   ├── hello.go        // hello service code
│   └── hello_test.go   // tests for hello service
│
└── world               // world service (a Go package)
    └── world.go        // world service code
```

--------------------------------

### Configure Custom Go Runtime Path

Source: https://encore.dev/docs/go/develop/env-vars

Sets the path to a custom Encore Go runtime installation.

```bash
export ENCORE_GOROOT=/path/to/custom/encore-go
```

--------------------------------

### Setup Database Proxy

Source: https://encore.dev/docs/go/cli/cli-reference

Configures a local proxy to forward connections to databases in a specific environment.

```shell
$ encore db proxy [--env=<name>] [flags]
```

--------------------------------

### Start Temporal and Encore locally

Source: https://encore.dev/docs/go/how-to/temporal

Run these commands in separate terminal windows to initialize the local development environment.

```bash
$ temporalite start --namespace default
$ encore run
```

--------------------------------

### Define initial database schema

Source: https://encore.dev/docs/go/primitives/databases

Example SQL migration file content for creating a new table in a service.

```sql
CREATE TABLE todo_item (
    id BIGSERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    done BOOLEAN NOT NULL DEFAULT false
);
```

--------------------------------

### Project Structure with Sub-packages

Source: https://encore.dev/docs/go/primitives/app-structure

Example of a project layout incorporating a sub-package within a service.

```text
/my-app
├── encore.app                       // ... and other top-level project files
│
├── hello                            // hello service (a Go package)
│   ├── migrations                   // hello service db migrations (directory)
│   │   └── 1_create_table.up.sql    // hello service db migration
│   ├── foo                          // sub-package foo (directory)
│   │   └── foo.go                   // foo code (cannot define APIs)
│   ├── hello.go                     // hello service code
│   └── hello_test.go                // tests for hello service
│
└── world                            // world service (a Go package)
    └── world.go                     // world service code
```

--------------------------------

### Install Encore skills package

Source: https://encore.dev/docs/go/ai-integration

Adds the Encore skills package to enable integration with various AI agents.

```bash
npx add-skill encoredev/skills
```

--------------------------------

### Customize Encore Docker builds

Source: https://encore.dev/docs/go/self-host/ci-cd

Examples of using flags to specify services, base images, and target architectures during the build process.

```bash
# Build specific services and gateways
encore build docker --services=service1,service2 --gateways=api-gateway MY-IMAGE:TAG

# Customize the base image
encore build docker --base=node:18-alpine MY-IMAGE:TAG

# Build for a specific architecture (useful when CI and deploy targets differ)
encore build docker --arch=arm64 MY-IMAGE:TAG
```

--------------------------------

### Define external database connection string

Source: https://encore.dev/docs/go/primitives/connect-existing-db

Example format for a PostgreSQL connection string used to connect to an external database.

```text
postgresql://user:password@externaldb-do-user-1234567-0.db.ondigitalocean.com:25010/externaldb?sslmode=require
```

--------------------------------

### Install Encore Toolbar via script tag

Source: https://encore.dev/docs/go/how-to/encore-toolbar

Add this script tag to the HTML head to initialize the toolbar. It must be loaded before application code without async or defer attributes to ensure proper interception of fetch and XMLHttpRequest.

```html
<script src="https://encore.dev/encore-toolbar.js"></script>
```

```html
<script src="https://encore.dev/encore-toolbar.js?appId=my-app&envName=staging"></script>
```

--------------------------------

### Create an Encore application

Source: https://encore.dev/docs/go/tutorials/uptime

Initialize a new project using the uptime tutorial starting-point branch.

```shell
$ encore app create uptime --example=github.com/encoredev/example-app-uptime/tree/starting-point
```

--------------------------------

### Initialize gqlgen tools

Source: https://encore.dev/docs/go/tutorials/graphql

Create a tools.go file to manage gqlgen dependencies.

```go
//go:build tools

package tools

import (
    _ "github.com/99designs/gqlgen"
    _ "github.com/99designs/gqlgen/graphql/introspection"
)
```

--------------------------------

### Initialize SQL Database and Schema

Source: https://encore.dev/docs/go/primitives/code-snippets

Define a database instance and its migration directory using sqldb.DatabaseConfig.

```go
-- todo/db.go --
package todo

// Create the todo database and assign it to the "tododb" variable
var tododb = sqldb.NewDatabase("todo", sqldb.DatabaseConfig{
	Migrations: "./migrations",
})

// Then, query the database using db.QueryRow, db.Exec, etc.
-- todo/migrations/1_create_table.up.sql --
CREATE TABLE todo_item (
  id BIGSERIAL PRIMARY KEY,
  title TEXT NOT NULL,
  done BOOLEAN NOT NULL DEFAULT false
  -- etc...
);
```

--------------------------------

### Define and use a database in Go

Source: https://encore.dev/docs/go/primitives/databases

Demonstrates initializing a database with migrations and executing an insert statement.

```go
// insert inserts a todo item into the database.
func insert(ctx context.Context, id, title string, done bool) error {
	_, err := tododb.Exec(ctx, `
		INSERT INTO todo_item (id, title, done)
		VALUES ($1, $2, $3)
	`, id, title, done)
	return err
}
```

```go
package todo

// Create the todo database and assign it to the "tododb" variable
var tododb = sqldb.NewDatabase("todo", sqldb.DatabaseConfig{
  Migrations: "./migrations",
})

// Then, query the database using db.QueryRow, db.Exec, etc.
```

```sql
CREATE TABLE todo_item (
  id BIGSERIAL PRIMARY KEY,
  title TEXT NOT NULL,
  done BOOLEAN NOT NULL DEFAULT false
  -- etc...
);
```

--------------------------------

### Initialize booking service file

Source: https://encore.dev/docs/go/tutorials/booking-system

Create the slots.go file within the booking directory.

```shell
$ touch booking/slots.go
```

--------------------------------

### Ping API response example

Source: https://encore.dev/docs/go/tutorials/uptime

Example JSON response returned by the Ping endpoint.

```json
{"up": true}
```

--------------------------------

### Create user service files

Source: https://encore.dev/docs/go/tutorials/booking-system

Initialize the user service directory and auth file.

```shell
$ mkdir user
$ touch user/auth.go
```

--------------------------------

### Install gops for Goland debugging

Source: https://encore.dev/docs/go/how-to/debug

Installs the gops package required for attaching the Goland debugger to a running process.

```shell
go get -t github.com/google/gops/
```

--------------------------------

### Initialize Service Directory

Source: https://encore.dev/docs/go/tutorials/uptime

Create the service directory and migrations folder structure.

```shell
$ mkdir site
$ mkdir site/migrations
```

--------------------------------

### Create an Encore application

Source: https://encore.dev/docs/go/tutorials/graphql

Initialize a new project using the url-shortener template.

```shell
$ encore app create --example=url-shortener
```

--------------------------------

### Define GET Endpoint with Query Parameters

Source: https://encore.dev/docs/go/primitives/defining-apis

Structs passed as the last argument in a function signature are automatically parsed from the query string for GET, HEAD, and DELETE methods.

```go
type ListParams struct {
    Limit uint // number of blog posts to return
    Offset uint // number of blog posts to skip, for pagination
}

type ListResponse struct {
    Posts []*BlogPost
}

//encore:api public method=GET path=/blog
func ListBlogPosts(ctx context.Context, opts *ListParams) (*ListResponse, error) {
    // Use limit and offset to query database...
}
```

--------------------------------

### Example API response

Source: https://encore.dev/docs/go/tutorials/booking-system

The JSON structure returned by the GetBookableSlots endpoint.

```json
{
  "Slots": [
    {
      "start": "2024-12-01T09:00:00Z",
      "end": "2024-12-01T10:00:00Z"
    },
    {
      "start": "2024-12-01T10:00:00Z",
      "end": "2024-12-01T11:00:00Z"
    },
    {
      "start": "2024-12-01T11:00:00Z",
      "end": "2024-12-01T12:00:00Z"
    },
    ...
  ]
}
```

--------------------------------

### Initialize Database Object

Source: https://encore.dev/docs/go/tutorials/rest-api

Define the database instance pointing to the migrations folder.

```go
-- url/url.go --
// Define a database named 'url', using the database
// migrations in the "./migrations" folder.

var db = sqldb.NewDatabase("url", sqldb.DatabaseConfig{
	Migrations: "./migrations",
})
```

--------------------------------

### Check Encore version

Source: https://encore.dev/docs/go/install

Displays the currently installed version of the Encore CLI.

```shell
encore version v1.28.0
```

--------------------------------

### Build a CLI tool with Encore client

Source: https://encore.dev/docs/go/cli/client-generation

Initializes a client with environment and authentication, then executes a service call with error handling for specific API error codes.

```go
package main

import (
    "context"
    "fmt"
    "os"
    "time"

    "shorten_cli/client"
)

func main() {
    // Create a new client with the default BaseURL
    client, err := client.New(
        client.Environment("production"),
        client.WithAuth(os.Getenv("SHORTEN_API_KEY")),
    )
    if err != nil {
        panic(err)
    }

    // Timeout if the request takes more than 5 seconds
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    // Call the Shorten function in the URL service
    resp, err := client.Url.Shorten(
        ctx,
        client.UrlShortenParams{ URL: os.Args[1] },
    )
    if err != nil {
        // Check the error returned
        if err, ok := err.(*client.APIError); ok {
            switch err.Code {
            case client.ErrUnauthenticated:
                fmt.Println("SHORTEN_API_KEY was invalid, please check your environment")
                os.Exit(1)
            case client.ErrAlreadyExists:
                fmt.Println("The URL you provided was already shortened")
                os.Exit(0)
            }
        }
        panic(err) // if here then something has gone wrong in an unexpected way
    }
    fmt.Printf("https://short.encr.app/%s", resp.ID)
}
```

--------------------------------

### Return an API error

Source: https://encore.dev/docs/go/primitives/api-errors

Example of returning an error from an Encore API endpoint.

```go
return &errs.Error{
	Code: errs.NotFound,
	Message: "sprocket not found",
}
```

--------------------------------

### Create Availability File

Source: https://encore.dev/docs/go/tutorials/booking-system

Command to initialize the Go source file for availability logic.

```shell
$ touch booking/availability.go
```

--------------------------------

### Initialize a PostgreSQL database

Source: https://encore.dev/docs/go/primitives/databases

Define a database resource using sqldb.NewDatabase within an Encore service, specifying the path to migration files.

```go
package todo

// Create the todo database and assign it to the "tododb" variable
var tododb = sqldb.NewDatabase("todo", sqldb.DatabaseConfig{
	Migrations: "./migrations",
})

// Then, query the database using db.QueryRow, db.Exec, etc.
```

```sql
CREATE TABLE todo_item (
  id BIGSERIAL PRIMARY KEY,
  title TEXT NOT NULL,
  done BOOLEAN NOT NULL DEFAULT false
  -- etc...
);
```

--------------------------------

### Unimplemented Resolver Stub

Source: https://encore.dev/docs/go/tutorials/graphql

Example of an auto-generated resolver method stub that requires implementation.

```go
// Shorten is the resolver for the shorten field.
func (r *mutationResolver) Shorten(ctx context.Context, input string) (*url.URL, error) {
	panic(fmt.Errorf("not implemented: Shorten - shorten"))
}
```

--------------------------------

### Configure Site Service

Source: https://encore.dev/docs/go/tutorials/uptime

Initialize the service and inject the GORM database connection.

```go
-- site/service.go --
// Service site keeps track of which sites to monitor.
package site

import (
	"encore.dev/storage/sqldb"
	"gorm.io/driver/postgres"
	"gorm.io/gorm"
)

//encore:service
type Service struct {
	db *gorm.DB
}

// Define a database named 'site', using the database migrations
// in the "./migrations" folder. Encore automatically provisions,
// migrates, and connects to the database.
var db = sqldb.NewDatabase("site", sqldb.DatabaseConfig{
	Migrations: "./migrations",
})

// initService initializes the site service.
// It is automatically called by Encore on service startup.
func initService() (*Service, error) {
	db, err := gorm.Open(postgres.New(postgres.Config{
		Conn: db.Stdlib(),
	}))
	if err != nil {
		return nil, err
	}
	return &Service{db: db}, nil
}
```

--------------------------------

### Update Encore CLI

Source: https://encore.dev/docs/go/install

Updates the local Encore CLI installation to the latest available version.

```bash
encore version update
```

--------------------------------

### Initialize LLM Rules

Source: https://encore.dev/docs/go/cli/cli-reference

Sets up LLM rules files within the current application directory.

```shell
$ encore llm-rules init [flags]
```

--------------------------------

### Define an Encore API endpoint

Source: https://encore.dev/docs/go/develop/testing/mocking

An example of an Encore API endpoint that calls an external service.

```go
//encore:api private
func GetPrice(ctx context.Context, p *PriceParams) (*PriceResponse, error) {
    // Call external API to get the price
}
```

--------------------------------

### Implement GetNote endpoint

Source: https://encore.dev/docs/go/tutorials/meeting-notes

Handles GET requests to retrieve a specific note by its ID from the database.

```go
//encore:api public method=GET path=/note/:id
func GetNote(ctx context.Context, id string) (*Note, error) {
	note := &Note{ID: id}

	// We use the note ID to query the database for the note's text and cover URL.
	err := sqldb.QueryRow(ctx, `
		SELECT text, cover_url FROM note
		WHERE id = $1
	`, id).Scan(&note.Text, &note.CoverURL)

	// If the note doesn't exist, we return an error.
	if err != nil {
		return nil, err
	}

	// Otherwise, we return the note.
	return note, nil
}
```

--------------------------------

### Create new Encore application

Source: https://encore.dev/docs/go/migration/ai-migration

Initialize a new Encore project using the empty template to serve as the destination for the migration.

```bash
encore app create
```

--------------------------------

### Get Database Connection URI

Source: https://encore.dev/docs/go/cli/cli-reference

Outputs the connection string for a database. Defaults to the local environment.

```shell
$ encore db conn-uri [<db-name>] [--env=<name>] [flags]
```

--------------------------------

### Manage Encore skills and agents

Source: https://encore.dev/docs/go/ai-integration

Commands for listing available skills and installing them for specific AI agents.

```bash
# List available skills
npx add-skill encoredev/skills --list

# Install to specific agents
npx add-skill encoredev/skills -a cursor -a claude-code
```

--------------------------------

### Instantiate a service for testing

Source: https://encore.dev/docs/go/how-to/dependency-injection

Manually initialize the service struct with a mock implementation during unit tests.

```go
func TestFoo(t *testing.T) {
    svc := &Service{sendgridClient: &myMockClient{}}
    // ...
}
```

--------------------------------

### Initialize monitor service directory

Source: https://encore.dev/docs/go/tutorials/uptime

Create the directory and file structure for the monitor service.

```shell
$ mkdir monitor
$ touch monitor/ping.go
```

--------------------------------

### Initialize an existing repository

Source: https://encore.dev/docs/go/cli/cli-reference

Registers a local repository as a new application on Encore Cloud.

```shell
$ encore app init [name] [flags]
```

--------------------------------

### Secret entry examples

Source: https://encore.dev/docs/go/cli/cli-reference

Demonstrates setting secrets via interactive terminal input or by piping from a file.

```shell
$ encore secret set --type dev MySecret
Enter secret value: ...
Successfully created secret value for MySecret.
```

```shell
$ encore secret set --type dev,local MySecret < my-secret.txt
Successfully created secret value for MySecret.
```

--------------------------------

### Full React integration example

Source: https://encore.dev/docs/go/how-to/logto-auth

Complete configuration and protected component implementation for Logto and Encore integration.

```tsx
-- config/logto.tsx --
import { LogtoConfig } from '@logto/react'

export const config: LogtoConfig = {
  endpoint: '<your-logto-endpoint>',
  appId: '<your-app-id>',
  resources: ['<your-api-resource-indicator>'],
}

export const appConfig = {
  apiResourceIndicator: '<your-api-resource-indicator>',
  signInRedirectUri: '<your-sign-in-redirect-uri>',
  signOutRedirectUri: '<your-sign-out-redirect-uri>',
}

export const encoreApiEndpoint = '<your-encore-api-endpoint>'
-- pages/ProtectedResource.tsx --
import { useLogto } from "@logto/react";
import { useState } from "react";
import { Navigate } from "react-router-dom";
import { appConfig, encoreApiEndpoint } from "../config/logto";

export function ProtectedResource() {
  const { isAuthenticated, getAccessToken } = useLogto();
  const [message, setMessage] = useState("");
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState("");

  const fetchProtectedResource = async () => {
    setIsLoading(true);
    setError("");
    try {
      const accessToken = await getAccessToken(appConfig.apiResourceIndicator);
      const response = await fetch(`${encoreApiEndpoint}/api/hello`, {
        headers: {
          Authorization: `Bearer ${accessToken}`,
        },
      });
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }
      const data = await response.json();
      setMessage(JSON.stringify(data));
    } catch (error) {
      console.error("Error fetching protected resource:", error);
      setError("Failed to fetch protected resource. Please try again.");
    } finally {
      setIsLoading(false);
    }
  };

  if (!isAuthenticated) {
    return <Navigate to="/" replace />;
  }

  return (
    <div>
      <h2>Protected Resource</h2>

      {message && !error && (
        <div>
          <h3>Response from Protected API</h3>
          <pre>{message}</pre>
        </div>
      )}

      <button
        onClick={fetchProtectedResource}
        disabled={isLoading}
      >
        {isLoading ? "Loading..." : "Fetch protected resource"}
      </button>

      {error && <div>{error}</div>}
    </div>
  );
}
```

--------------------------------

### Define and use a simple integer Keyspace

Source: https://encore.dev/docs/go/primitives/caching

Demonstrates creating an integer keyspace for rate limiting and using it within middleware to track request counts.

```go
import (
    "encore.dev/beta/auth"
    "encore.dev/beta/errs"
    "encore.dev/middleware"
)

// RequestsPerUser tracks the number of requests per user.
// The cache items expire after 10 seconds without activity.
var RequestsPerUser = cache.NewIntKeyspace[auth.UID](cluster, cache.KeyspaceConfig{
	KeyPattern:    "requests/:key",
	DefaultExpiry: cache.ExpireIn(10 * time.Second),
})

// RateLimitMiddleware is a global middleware that limits the number of authenticated requests
// to 10 requests per 10 seconds.
//encore:middleware target=all
func RateLimitMiddleware(req middleware.Request, next middleware.Next) middleware.Response {
	if userID, ok := auth.UserID(); ok {
		val, err := RequestsPerUser.Increment(req.Context(), userID, 1)

		// NOTE: this "fails open", meaning if we can't communicate with the cache
		// we default to allowing the requests.
		//
		// Consider whether that's the correct behavior for your application,
		// or if you want to return an error to the user in that case.
		if err == nil && val > 10 {
			return middleware.Response{
				Err: &errs.Error{Code: errs.ResourceExhausted, Message: "rate limit exceeded"},
			}
		}
	}
	return next(req)
}
```

--------------------------------

### Example Telemetry Data Payload

Source: https://encore.dev/docs/go/cli/telemetry

JSON structure representing the telemetry data sent by the Encore CLI.

```json
{
    "event": "app.create",
    "anonymousId": "a-uuid-unique-for-the-installation",
    "properties": {
        "error": false,
        "lang": "go",
        "template": "graphql"
    }
}
```

--------------------------------

### Manage CLI configuration

Source: https://encore.dev/docs/go/cli/cli-reference

Gets or sets configuration values for the Encore CLI, either globally or per-application.

```shell
$ encore config <key> [<value>] [flags]
```

--------------------------------

### Implement the Connect Greet Service

Source: https://encore.dev/docs/go/how-to/grpc-connect

Defines the GreetServer struct and implements the Greet method using the Connect RPC framework.

```go
package greet

import (
	"context"
	"fmt"
	"log"

	"connectrpc.com/connect"

	greetv1 "encore.app/gen/greet/v1" // generated by protoc-gen-go
)

type GreetServer struct{}

func (s *GreetServer) Greet(
	ctx context.Context,
	req *connect.Request[greetv1.GreetRequest],
) (*connect.Response[greetv1.GreetResponse], error) {
	log.Println("Request headers: ", req.Header())
	res := connect.NewResponse(&greetv1.GreetResponse{
		Greeting: fmt.Sprintf("Hello, %s!", req.Msg.Name),
	})
	res.Header().Set("Greet-Version", "v1")
	return res, nil
}
```

--------------------------------

### Run Encore in debug mode

Source: https://encore.dev/docs/go/how-to/debug

Starts the Encore application and displays the Process ID required for attaching a debugger.

```shell
$ encore run --debug
API Base URL:      http://localhost:4000
Dev Dashboard URL: http://localhost:9400/hello-world-cgu2
Process ID:        51894
1:48PM TRC registered endpoint path=/hello/:name service=hello endpoint=Hello
```

--------------------------------

### Mount the Connect Service in Encore

Source: https://encore.dev/docs/go/how-to/grpc-connect

Initializes the Connect service handler and exposes it via an Encore raw endpoint.

```go
package greet

import (
	"net/http"

	"encore.app/gen/greet/v1/greetv1connect"
	"golang.org/x/net/http2"
	"golang.org/x/net/http2/h2c"
)

//encore:service
type Service struct {
	routes http.Handler
}

//encore:api public raw path=/greet.v1.GreetService/*endpoint
func (s *Service) GreetService(w http.ResponseWriter, req *http.Request) {
	s.routes.ServeHTTP(w, req)
}

func initService() (*Service, error) {
	greeter := &GreetServer{}
	mux := http.NewServeMux()
	path, handler := greetv1connect.NewGreetServiceHandler(greeter)
	mux.Handle(path, handler)
	return &Service{routes: mux}, nil
}
```

--------------------------------

### Start Encore in Debug Mode

Source: https://encore.dev/docs/go/how-to/debug

Launch the application with a headless Delve server that pauses execution until a debugger attaches.

```shell
$ encore run --debug=break
API Base URL:      http://localhost:4000
Dev Dashboard URL: http://localhost:9400/hello-world-cgu2

API server listening at: 127.0.0.1:2345
```

--------------------------------

### Example HTTP request and response for nested structs

Source: https://encore.dev/docs/go/primitives/defining-apis

Demonstration of how the NestedRequestResponse struct is unmarshalled from a request and marshalled into a response.

```output
POST /example?query=a%20query HTTP/1.1
Content-Type: application/json
X-Header: A header

{
   "body1": "a body",
   "nested": {
      "Header2": "not a header",
      "Query2": "not a query",
      "body2": "a nested body"
   }
}
```

```output
HTTP/1.1 200 OK
Content-Type: application/json
X-Header: A header

{
   "Query": "not a query",
   "body1": "a body",
   "nested": {
      "Header2": "not a header",
      "Query2": "not a query",
      "body2": "a nested body"
   }
}
```

--------------------------------

### Implement Cloud-Specific Logic

Source: https://encore.dev/docs/go/develop/metadata

Use encore.Meta().Environment.Cloud to conditionally execute logic based on the deployment provider.

```go
package audit

import (
    "encore.dev"
    "encore.dev/beta/auth"
)

func Audit(ctx context.Context, action message, user auth.UID) error {
    switch encore.Meta().Environment.Cloud {
    case encore.CloudAWS:
        return writeIntoRedshift(ctx, action, user)
    case encore.CloudGCP:
        return writeIntoBigQuery(ctx, action, user)
    case encore.CloudLocal:
        return writeIntoFile(ctx, action, user)
    default:
        return fmt.Errorf("unknown cloud: %s", encore.Meta().Environment.Cloud)
    }
}
```

--------------------------------

### Execute migration generation

Source: https://encore.dev/docs/go/how-to/atlas-gorm

Make the generation script executable and run it to create the first migration.

```shell
$ chmod +x blog/scripts/generate-migration
$ cd blog && ./scripts/generate-migration init
```

--------------------------------

### GitHub Actions Workflow for Frontend Deployment

Source: https://encore.dev/docs/go/tutorials/meeting-notes

This workflow automates the installation, build, and deployment process to the gh-pages branch on every push.

```yaml
name: Build and Deploy

on: [push]

permissions:
  contents: write

jobs:
  build-and-deploy:
    concurrency: ci-${{ github.ref }}
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: frontend

    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v3

      - name: Use Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "16.15.1"

      - name: Install and Build 🔧
        run: |
          npm install
          npm run build

      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@v4.3.3
        with:
          branch: gh-pages
          folder: frontend/dist
```

--------------------------------

### Call REST API endpoint via curl

Source: https://encore.dev/docs/go/tutorials/rest-api

Executes a GET request to the local development server to retrieve a shortened URL.

```shell
$ curl http://localhost:4000/url/zr6RmZc4
```

--------------------------------

### Initialize Temporal Service in Encore

Source: https://encore.dev/docs/go/how-to/temporal

Sets up the Temporal client and worker within an Encore service, using an environment-specific task queue.

```go
-- greeting/greeting.go --
package greeting

import (
	"context"
	"fmt"

	"go.temporal.io/sdk/client"
	"go.temporal.io/sdk/worker"
	"encore.dev"
)

// Use an environment-specific task queue so we can use the same
// Temporal Cluster for all cloud environments.
var (
    envName = encore.Meta().Environment.Name
    greetingTaskQueue = envName + "-greeting"
)

//encore:service
type Service struct {
	client client.Client
	worker worker.Worker
}

func initService() (*Service, error) {
	c, err := client.Dial(client.Options{})
	if err != nil {
		return nil, fmt.Errorf("create temporal client: %v", err)
	}

	w := worker.New(c, greetingTaskQueue, worker.Options{})

	err = w.Start()
	if err != nil {
		c.Close()
		return nil, fmt.Errorf("start temporal worker: %v", err)
	}
	return &Service{client: c, worker: w}, nil
}

func (s *Service) Shutdown(force context.Context) {
	s.client.Close()
	s.worker.Stop()
}
```

--------------------------------

### Test gRPC service with grpcurl and curl

Source: https://encore.dev/docs/go/how-to/grpc-connect

Commands to install grpcurl and perform requests against the gRPC service using both grpcurl and standard curl.

```shell
# Install grpcurl if you haven't already
$ go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

# Call the service with grpcurl
grpcurl \
    -protoset <(buf build -o -) -plaintext \
    -d '{"name": "Jane"}' \
    localhost:4000 greet.v1.GreetService/Greet
{"greeting": "Hello, Jane!"} 

# Or call the service with curl
$ curl -H "Content-Type: application/json" -d '{"name": "Jane"}' http://localhost:4000/greet.v1.GreetService/Greet
{"greeting":"Hello, Jane!"}  # Expected response
```
Tokens:
Raw