API reference

The public API is split by trust boundary. Import browser-safe UI from ludicord, route controls from ludicord/navigation, Activity state from ludicord/activity, Discord context from ludicord/discord, trusted request helpers from ludicord/server, and realtime primitives from the explicit WebSocket entry points.

#Core UI and Activity hooks

1import {
2  Link,
3  Minimize,
4} from "ludicord";
5import {
6  useActivityLifecycle,
7  useActivityPresence,
8  useActivityQuery,
9  useActivityStorage,
10  useGameLoop,
11  useSharedActivityState,
12} from "ludicord/activity";

The runtime also exports LudicordActivity, EmbedOutlet, loading and error boundaries, metadata helpers, and generated route types. A generated app connects these automatically; most Activity screens only need hooks and Link.

#Navigation

1import { Link, useEmbedPath, useEmbedParams, useEmbedRouter } from "ludicord/navigation";
2
3const router = useEmbedRouter();
4const path = useEmbedPath();
5const params = useEmbedParams<"/game/[room]">();

useEmbedRouter() provides push, replace, back, and prefetch behavior. Route unions and parameter maps are generated into .ludicord; an invalid literal route is a TypeScript error after the route manifest refreshes.

#Authentication

1import {
2  authenticateLudicord,
3  useAuthError,
4  useAuthStatus,
5  useLudicordAuth,
6  useLudicordSession,
7} from "ludicord/auth";

Prefer useLudicordAuth() in UI. Use the smaller hooks when a component should subscribe to only one part of the auth snapshot.

#Discord context

1import {
2  useDiscordData,
3  useDiscordUser,
4  useDiscordGuild,
5  useDiscordChannel,
6  useParticipants,
7  useVoiceState,
8} from "ludicord/discord";

The Discord entry point includes context hooks, server-backed resource hooks, event subscriptions, asset URL helpers, responsive layout data, and diagnostics.

Normalized Discord records expose a .raw value when you need a field that Ludicord does not normalize. Treat raw fields as optional because Discord can change payload shape or omit data based on scope and context.

#Server APIs

1import {
2  getLudicordSession,
3  requireLudicordSession,
4  createDiscordRest,
5} from "ludicord/server";
6import type { LudicordRequest } from "ludicord/server";

getLudicordSession(request) returns a session or null. requireLudicordSession(request) returns the session or throws an authenticated response error. createDiscordRest() provides typed REST access with the server token; never import it into an embed.

createMemorySessionDataStore() is available for controlled session-store configuration. The default store is bounded and process-local; use an application-owned shared implementation when multiple production processes must read the same sessions. Do not import compiler or runtime internals to add middleware-like behavior.

#WebSocket APIs

1import { defineWS } from "ludicord/ws/server";
2
3export default defineWS({
4  open(client) {
5    client.join(`activity:${client.ludicord.instanceId}`);
6  },
7  message(client, message) {
8    client.broadcast("audience:update", message);
9  },
10});

Use defineWS on the server, useWS in React, and defineSharedActivityState with useSharedActivityState when you want a state protocol instead of manual events. WebSocket clients receive verified Ludicord session and Activity context when authentication is enabled.

#Type imports

Use import type for types so they disappear from the client bundle.

1import type { LudicordEmbedRoute } from "ludicord/navigation";
2import type { LudicordDiscordUser } from "ludicord/discord";
3import type { LudicordRequest } from "ludicord/server";
4import type { LudicordWSConnection } from "ludicord/ws/client";

The generated route registry augments these types after ludicord dev or ludicord build scans the project. If a new route is missing from autocomplete, save the route file and wait for the manifest compile to finish.

#Choose the correct entry point

1. Start with ludicord for framework-owned Activity components.
2. Add ludicord/navigation, ludicord/activity, and ludicord/discord for their browser-safe capabilities.
3. Use ludicord/server, ludicord/security, and ludicord/ws/server only in server-owned modules.
4. Use ludicord/ws/client for realtime React code.
5. Keep ludicord/testing in test files, and never import ludicord/internal from application code.

Next, use the CLI reference to understand the commands that compile and inspect these boundaries.