mcpField
E
encore-pubsub

encore-pubsub

github.com/encoredevDevelopment30429 installsUpdated 2d ago
Repository

About encore-pubsub

encore-pubsub is a skill for asynchronous messaging between Encore services. It covers publishing through Topics, handling events with Subscriptions, and choosing delivery guarantees.

Key features

  1. 01Publish events through Topics
  2. 02Handle events with Subscriptions
  3. 03Mark filter or ordering fields with Attribute
  4. 04Pass publishing access through Publisher references
  5. 05Configure at-least-once or exactly-once delivery

Use cases

  1. 01Send events asynchronously between services
  2. 02Handle domain events such as order creation
  3. 03Filter or order messages by attributes
  4. 04Move slow work out of publish callers

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/encoredev/skills --skill encore-pubsub

After installing, type/encore-pubsubin Claude Code to confirm it loaded.

Details

From the project README

Encore 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 at package level — never inside functions.

Topics

import { Topic } from "encore.dev/pubsub";

interface OrderCreatedEvent {
  orderId: string;
  userId: string;
  total: number;
}

// Package level declaration
export const orderCreated = new Topic<OrderCreatedEvent>("order-created", {
  deliveryGuarantee: "at-least-once",
});
Publishing
await orderCreated.publish({
  orderId: "123",
  userId: "user-456",
  total: 99.99,
});
Subscriptions
import { Subscription } from "encore.dev/pubsub";

const _ = new Subscription(orderCreated, "send-confirmation-email", {
  handler: async (event) => {
    await sendEmail(event.userId, event.orderId);
  },
});
Message Attributes

Use Attribute<T> for fields that should be treated as message attributes (for filtering/ordering):

import { Topic, Attribute } from "encore.dev/pubsub";

interface CartEvent {
  cartId: Attribute<string>;  // Used for ordering
  userId: string;
  action: "add" | "remove";
  productId: string;
}

// Ordered topic: events with same cartId delivered in order
export const cartEvents = new Topic<CartEvent>("cart-events", {
  deliveryGuarantee: "at-least-once",
  orderingAttribute: "cartId",
});
Topic References

Pass topic access to other code while maintaining static analysis:

import { Publisher } from "encore.dev/pubsub";

const publisherRef = orderCreated.ref<Publisher>();

async function notifyOrder(ref: typeof publisherRef, orderId: string) {
  await ref.publish({ orderId, userId: "123", total: 99.99 });
}

Delivery Guarantees

  • at-least-once (default): may deliver duplicates → handlers must be idempotent.
  • exactly-once: 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 at package level.
  • Subscription handlers must be idempotent (at-least-once delivery is the default).
  • Use Attribute<T> for fields meant for filtering/ordering, not for arbitrary metadata.
  • Don't do heavy synchronous work in publish callers — publish returns once the message is queued.

Comments

Markdown supported