@cstar.help/svelte

@cstar.help/svelte

Svelte 5 rune classes for the cStar customer support platform. Build custom chat widgets and knowledge base UIs with reactive $state classes.

• Svelte 5 runes — $state classes, not stores
• Three modules — Chat (real-time messaging), Library (knowledge base), and Community (forum)
• TypeScript-first — full type definitions included
• Tiny — ~15 KB, tree-shakeable, only peer deps

Install

npm install @cstar.help/svelte @cstar.help/js

Chat

Wrap your app in <CStarChatProvider> and instantiate state classes in child components.

Setup

<script>
	import { CStarChatProvider } from '@cstar.help/svelte';
</script>

<CStarChatProvider teamSlug="acme">
	<ChatWidget />
</CStarChatProvider>

Identify the Customer

<script>
	import { ChatState, getChatClient } from '@cstar.help/svelte';

	const client = getChatClient();
	const chat = new ChatState(client);

	async function connect() {
		await chat.identify(
			{ externalId: 'usr_123', email: '[e-mail]', timestamp: Math.floor(Date.now() / 1000) },
			hmacSignature // computed server-side
		);
	}
</script>

{#if chat.isIdentified}
	<p>Connected! Realtime: {chat.isRealtimeReady}</p>
{:else}
	<button onclick={connect}>Connect</button>
{/if}

Tickets

<script>
	import { TicketsState, getChatClient } from '@cstar.help/svelte';

	const client = getChatClient();
	const tix = new TicketsState(client); // auto-fetches on creation
</script>

{#if tix.isLoading}
	<p>Loading...</p>
{:else}
	<ul>
		{#each tix.tickets as ticket (ticket.id)}
			<li>{ticket.subject}</li>
		{/each}
	</ul>
{/if}

Messages + Typing Indicators

<script>
	import { onDestroy } from 'svelte';
	import { MessagesState, TypingState, getChatClient } from '@cstar.help/svelte';

	let { ticketId } = $props();

	const client = getChatClient();
	const msgs = new MessagesState(client, ticketId); // auto-fetches + subscribes to real-time
	const typing = new TypingState(client, ticketId);

	let text = $state('');

	async function send() {
		await msgs.send(text); // optimistic — appears instantly
		text = '';
	}

	onDestroy(() => {
		msgs.destroy();
		typing.destroy();
	});
</script>

{#each msgs.messages as msg (msg.id)}
	<div>{msg.content}</div>
{/each}

{#each typing.typingAgents as agent (agent.agentId)}
	<p>{agent.agentName} is typing...</p>
{/each}

<input
	bind:value={text}
	oninput={() => typing.sendTyping(text.length > 0)}
	onkeydown={(e) => e.key === 'Enter' && send()}
/>

Knowledge Base

Wrap in <CStarLibraryProvider> for public knowledge base access — no auth required.

Setup

<script>
	import { CStarLibraryProvider } from '@cstar.help/svelte';
</script>

<CStarLibraryProvider teamSlug="acme">
	<HelpCenter />
</CStarLibraryProvider>

Categories + Articles

<script>
	import { CategoriesState, ArticlesState, getLibraryClient } from '@cstar.help/svelte';

	const client = getLibraryClient();
	const cats = new CategoriesState(client);
	const articles = new ArticlesState(client, { categorySlug: 'getting-started' });
</script>

<nav>
	{#each cats.categories as cat (cat.id)}
		<a>{cat.name}</a>
	{/each}
</nav>

<ul>
	{#each articles.articles as article (article.id)}
		<li>{article.title}</li>
	{/each}
</ul>

Search with Debouncing

<script>
	import { onDestroy } from 'svelte';
	import { ArticleSearchState, getLibraryClient } from '@cstar.help/svelte';

	const client = getLibraryClient();
	const search = new ArticleSearchState(client); // 300ms debounce built-in

	onDestroy(() => search.destroy());
</script>

<input oninput={(e) => search.search(e.currentTarget.value)} placeholder="Search..." />

{#if search.isLoading}
	<p>Searching...</p>
{/if}

{#each search.results as article (article.id)}
	<a href="/articles/{article.slug}">{article.title}</a>
{/each}

Community

Wrap in <CStarCommunityProvider> for public community forum access — no auth required.

Setup

<script>
	import { CStarCommunityProvider } from '@cstar.help/svelte';
</script>

<CStarCommunityProvider teamSlug="acme">
	<CommunityForum />
</CStarCommunityProvider>

Topics + Posts

<script>
	import { TopicsState, PostsState, getCommunityClient } from '@cstar.help/svelte';

	const client = getCommunityClient();
	const topicsState = new TopicsState(client);
	const postsState = new PostsState(client, { sort: 'votes' });
</script>

<nav>
	{#each topicsState.topics as topic (topic.id)}
		<a>{topic.name}</a>
	{/each}
</nav>

<p>{postsState.count} posts</p>
<ul>
	{#each postsState.posts as post (post.id)}
		<li>{post.title} — {post.voteCount} votes</li>
	{/each}
</ul>

Single Post with Comments

<script>
	import { PostState, getCommunityClient } from '@cstar.help/svelte';

	let { slug } = $props();
	const client = getCommunityClient();
	const postState = new PostState(client, slug);
</script>

{#if postState.data}
	<h1>{postState.data.post.title}</h1>
	{#each postState.data.comments as comment (comment.id)}
		<p>{comment.body}</p>
	{/each}
{/if}

Search

<script>
	import { CommunitySearchState, getCommunityClient } from '@cstar.help/svelte';

	const client = getCommunityClient();
	const search = new CommunitySearchState(client);
</script>

<input oninput={(e) => search.search(e.currentTarget.value)} placeholder="Search posts..." />

{#if search.results}
	{#each search.results.data as post (post.id)}
		<a>{post.title}</a>
	{/each}
{/if}

API Reference

Chat Classes

Class	Reactive Properties	Methods	Cleanup
ChatState	isIdentified, isRealtimeReady, error	identify(customer, signature), disconnect()	No
TicketsState	tickets, isLoading, error, hasMore	refresh(), create(params)	No
MessagesState	messages, isLoading, error	send(content), refresh(), destroy()	Yes
TypingState	typingAgents	sendTyping(isTyping), destroy()	Yes

Library Classes

Class	Reactive Properties	Methods	Cleanup
CategoriesState	categories, isLoading, error	refresh()	No
ArticlesState	articles, isLoading, error	refresh(), getArticle(slug)	No
ArticleSearchState	results, totalCount, isLoading, error	search(query), destroy()	Yes

Community Classes

Class	Reactive Properties	Methods	Cleanup
TopicsState	topics, isLoading, error	refresh()	No
PostsState	posts, count, isLoading, error	refresh()	No
PostState	data, isLoading, error	refresh()	No
CommunitySearchState	results, isLoading, error	search(query)	No

Context Functions

Function	Returns	Description
getChatClient()	ChatClient	Get client from nearest CStarChatProvider
getLibraryClient()	LibraryClient	Get client from nearest CStarLibraryProvider
getCommunityClient()	CommunityClient	Get client from nearest CStarCommunityProvider

Classes marked Cleanup: Yes subscribe to real-time events or use timers. Call destroy() in onDestroy().

Requirements

• Svelte 5+
• @cstar.help/js 0.1.0+
• Node.js 18+ (for SSR with SvelteKit)

License

MIT