PresenceKit

Bring your Discord presence to your website.

PresenceKit is a lightweight TypeScript SDK for displaying real-time Discord status, games, activities, Spotify listening information, and more.

Built for JavaScript, TypeScript, React, Next.js, Vue, Svelte, and other modern web applications.

• Real-time updates — Live presence through Server-Sent Events (SSE), with automatic polling fallback.
• Rich activities — Display games, applications, Spotify tracks, and activity details.
• Smart artwork — Automatically resolve activity artwork, with graceful image fallbacks.
• Framework-friendly — Typed APIs, React hooks, reusable components, and framework integrations.
• Privacy-first — Only share presence information from users who have explicitly opted in.
• No Discord credentials required — Connect directly through PresenceKit's public API.

Installation

Option 1 — Install from npm (recommended)

The easiest way to get started is to install the official package using your preferred package manager.

npm

npm install @iconical/presencekit

pnpm

pnpm add @iconical/presencekit

Bun

bun add @iconical/presencekit

Yarn

yarn add @iconical/presencekit

Once installed, you're ready to integrate PresenceKit into your application.

Option 2 — Build manually from source

Prefer working directly with the source code? You can clone the repository, build the SDK, and install the generated package locally.

git clone https://github.com/himinthevoid/presencekit.git
cd presencekit
bun install
bun run build

Create a local npm package archive:

bun pm pack --filename presencekit-local.tgz

Then install the generated archive into your own project:

npm install /path/to/presencekit-local.tgz

This is useful for local development, testing unreleased features, or contributing to PresenceKit.

For more information, see the installation guide.

Quick start

Retrieve a Discord user's current presence:

import { createPresenceClient } from "@iconical/presencekit";

const client = createPresenceClient();

const result = await client.getPresence("123456789012345678");

console.log(result.profile.displayName);
console.log(result.presence?.status);
console.log(result.presence?.activities);

Replace the example ID with the Discord ID of a user who has enabled PresenceKit sharing.

React / Next.js

PresenceKit includes React hooks that manage live subscriptions, updates, and connection cleanup automatically.

"use client";

import { usePresence } from "@iconical/presencekit/react";

export default function DiscordPresence() {
  const { data, loading, error } = usePresence({
    userId: "123456789012345678",
  });

  if (loading) return <p>Connecting...</p>;
  if (error || !data?.presence) {
    return <p>Presence unavailable</p>;
  }

  return (
    <div>
      <h3>{data.profile.displayName}</h3>
      <p>Status: {data.presence.status}</p>
    </div>
  );
}

Looking for ready-made components? PresenceKit also provides reusable React UI components:

import { LivePresenceCard } from "@iconical/presencekit/react-ui";

<LivePresenceCard userId="123456789012345678" />;

Explore the framework guides for more examples.

How presence sharing works

PresenceKit is an opt-in service. Users decide whether their Discord presence can be shared through the public API.

To enable sharing, join the official PresenceKit Discord community and use the /confirm command.

To revoke access, use /disconnect.

Applications never need to request Discord account credentials or store Discord authentication tokens to read authorized presence data.

Documentation

Find detailed explanations, tutorials, API references, and examples in the official documentation.

• Getting started
• Installation
• Framework integrations
• Features
• API reference
• Development

API endpoint: https://presence-api.iconical.dev

The endpoint is configured automatically by the SDK.

Development

Want to contribute or work on the SDK locally?

bun install
bun test
bunx tsc --noEmit
bun run build

For additional checks:

bun run check:release
bun run check:boundary
bun run check:contract

See CONTRIBUTING.md for contribution guidelines and the changelog for project updates.

License

PresenceKit is distributed under the PresenceKit Source-Available License v1.0.

Personal and commercial application usage, contributions, and modifications are permitted under the license's terms. Redistribution of unchanged or lightly modified standalone copies is restricted.

PresenceKit is source-available software, not OSI-approved open source.

Built with ❤️ by Iconical.