
Description
Asynchronous messaging in Encore Go via `pubsub.NewTopic` and `pubsub.NewSubscription` from `encore.dev/pubsub` — broadcast events, decouple producers from consumers, and run background handlers.
SKILL.md
Encore Go Pub/Sub
Instructions
Pub/Sub is for asynchronous messaging between services. Producers publish events to a Topic; consumers attach Subscriptions to react. Resources must be declared as package-level variables — never inside functions.
Topics
package events
import "encore.dev/pubsub"
type OrderCreatedEvent struct {
OrderID string `json:"order_id"`
UserID string `json:"user_id"`
Total int `json:"total"`
}
// Package level declaration
var OrderCreated = pubsub.NewTopic[*OrderCreatedEvent]("order-created", pubsub.TopicConfig{
DeliveryGuarantee: pubsub.AtLeastOnce,
})
Publishing
msgID, err := events.OrderCreated.Publish(ctx, &events.OrderCreatedEvent{
OrderID: "123",
UserID: "user-456",
Total: 9999,
})
Subscriptions
package notifications
import (
"context"
"myapp/events"
"encore.dev/pubsub"
)
var _ = pubsub.NewSubscription(events.OrderCreated, "send-confirmation-email",
pubsub.SubscriptionConfig[*events.OrderCreatedEvent]{
Handler: sendConfirmationEmail,
},
)
func sendConfirmationEmail(ctx context.Context, event *events.OrderCreatedEvent) error {
// Send email...
return nil
}
Topic References
Pass topic access to library code while maintaining static analysis:
// Create a reference with publish permission
ref := pubsub.TopicRef[pubsub.Publisher[*OrderCreatedEvent]](OrderCreated)
// Use the reference in library code
func publishEvent(ref pubsub.Publisher[*OrderCreatedEvent], event *OrderCreatedEvent) error {
_, err := ref.Publish(ctx, event)
return err
}
Delivery Guarantees
pubsub.AtLeastOnce(default): may deliver duplicates → handlers must be idempotent.pubsub.ExactlyOnce: stricter, capped throughput (AWS 300 msg/s/topic, GCP 3000+ msg/s/region). Does not deduplicate on the publish side.
Guidelines
- Topics and subscriptions must be declared as package-level variables.
- Subscription handlers must be idempotent (at-least-once delivery is the default).
- Subscription handlers receive a
context.Contextand the event pointer; return anerrorto retry per the topic's retry policy. - Don't do heavy synchronous work in
Publishcallers —Publishreturns once the message is queued.
More skills from the skills repository
View all 28 skillsencore-api
build type-safe APIs with Encore
Apr 6API DevelopmentEncoreTypeScriptencore-auth
implement Encore.ts authentication
Apr 6AuthEncoreTypeScriptencore-bucket
store files in Encore.ts buckets
May 16BackendEncoreFile StorageFile Uploads +1encore-cache
cache data in Redis with Encore.ts
May 16BackendCachingEncoreRedis +1encore-code-review
review Encore.ts code
Apr 6Code ReviewEncoreTypeScriptencore-cron
schedule recurring jobs in Encore.ts
May 16AutomationBackendEncoreScheduling +1
More from Encore
View publisherencore-database
build Encore databases
skills
Apr 6DatabaseEncoreORMTypeScriptencore-frontend
connect frontend to Encore backend
skills
Apr 6EncoreFrontendNext.jsReactencore-getting-started
build and run applications with Encore.ts
skills
Apr 6API DevelopmentBackendEncoreLocal Development +2encore-go-api
build APIs with Encore Go
skills
Apr 6API DevelopmentEncoreGoencore-go-auth
implement authentication with Encore Go
skills
Apr 6AuthBackendEncoreGoencore-go-bucket
store files in Encore Go buckets
skills
May 16BackendEncoreFile StorageGo +1