Search documentation

Search pages and headings

Client Library

Installation

Install the client package and check your runtime meets its two requirements.

Install

npm install @gettersethya/yt-livechat-client
pnpm add @gettersethya/yt-livechat-client
yarn add @gettersethya/yt-livechat-client
bun add @gettersethya/yt-livechat-client

The package is ESM-only and ships its own type declarations.

Requirements

A running API server

The client never contacts YouTube. It talks only to a yt-livechat server — by default http://localhost:3000. See Quickstart to run one.

fetch with streaming response bodies

The client reads Server-Sent Events off a fetch response body, so it needs response.body as a ReadableStream plus TextDecoderStream — available in browsers, Node.js 18+, Bun and Deno alike. fetch is read from globalThis and can be replaced via the fetchFn option.

It deliberately does not use EventSource, which cannot be injected for tests and cannot be given a Last-Event-ID on its first connection.

Because the server sends CORS headers on every route, the client works from a browser page directly, with no proxy in between.

What the package exports

Export Kind Purpose
LiveChatApiClient class The SSE stream client
LiveChatStore class Framework-agnostic state store — see Framework Bindings
ApiHttpError class Every failure the client raises
extractVideoId function Reduce a URL or id to an 11-character video id
ILiveChatApiClient, ILiveChatStore types Interfaces of the two classes
LiveChatClientOptions type Constructor options
LiveChatConnectInput, LiveChatCoreOptions types Store constructor input and options
LiveChatState, LiveChatStatus types The store's snapshot shape and status union
ConnectedListener, MessageListener, ErrorListener, EndListener types Event handler signatures
FetchFn type The injectable fetch signature
MessageSchema, PartSchema, ThumbnailSchema, … schemas The shared request/response schemas

Framework subpath exports

Reactive bindings live behind subpaths so their framework never enters your bundle unless asked for. Each has its own optional peer dependency:

Import Peer Gives you
@gettersethya/yt-livechat-client/react react ^18 || ^19 useLiveChat, useVideoId
@gettersethya/yt-livechat-client/vue vue ^3.5 useLiveChat, useVideoId
@gettersethya/yt-livechat-client/svelte svelte ^5 useLiveChat, useVideoId

See Framework Bindings for usage.

The schemas are the same definitions the server validates against — the client package owns them and the server imports them, so the contract cannot drift between the two.

Verify the install

import { extractVideoId } from '@gettersethya/yt-livechat-client'

console.log(extractVideoId('https://youtu.be/zvwJ29RFVww'))
// -> "zvwJ29RFVww"

Next