Lifecycle & Config

Metadata

Metadata provides information about the currently running actor.

Actor ID

Get the unique instance ID of the actor:

import { actor } from "rivetkit";

const example = actor({
  state: {},
  actions: {
    getId: (c) => {
      const actorId = c.actorId;
      return actorId;
    }
  }
});

Actor Name

Get the actor type name:

import { actor } from "rivetkit";

const example = actor({
  state: {},
  actions: {
    getName: (c) => {
      const actorName = c.name;
      return actorName;
    }
  }
});

This is useful when you need to know which actor type is running, especially if you have generic utility functions that are shared between different actor implementations.

Actor Key

Get the actor key used to identify this actor instance:

import { actor } from "rivetkit";

const example = actor({
  state: {},
  actions: {
    getKey: (c) => {
      const actorKey = c.key;
      return actorKey;
    }
  }
});

The key is used to route requests to the correct actor instance and can include parameters passed when creating the actor.

Learn more about using keys for actor addressing and configuration in the keys documentation.

Region

Region can be accessed from the context object via c.region.

import { actor } from "rivetkit";

const example = actor({
  state: {},
  actions: {
    getRegion: (c) => {
      const region = c.region;
      return region;
    }
  }
});

c.region is only supported on Rivet at the moment.

Example Usage

import { actor, setup } from "rivetkit";

const chatRoom = actor({
  state: {
    messages: []
  },
  
  actions: {
    // Get actor metadata
    getMetadata: (c) => {
      return {
        actorId: c.actorId,
        name: c.name,
        key: c.key,
        region: c.region
      };
    }
  }
});

export const registry = setup({
  use: { chatRoom }
});

import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const chatRoom = actor({
  state: { messages: [] as string[] },
  actions: {
    getMetadata: (c) => ({
      actorId: c.actorId,
      name: c.name,
      key: c.key,
      region: c.region
    })
  }
});

const registry = setup({ use: { chatRoom } });
const client = createClient<typeof registry>("http://localhost:8080");

// Connect to a chat room
const chatRoomHandle = client.chatRoom.get(["general"]);

// Get actor metadata
const metadata = await chatRoomHandle.getMetadata();
console.log("Actor metadata:", metadata);

API Reference

ActorDefinition - Interface for defining metadata
CreateOptions - Includes metadata options