get-convex · stickerdaniel · Nov 26, 2025 · coderabbitai · Nov 26, 2025 · ianmacartney
diff --git a/example-svelte/README.md b/example-svelte/README.md
@@ -0,0 +1,59 @@
+# Svelte Example - Persistent Text Streaming
+
+This is a Svelte 5 example demonstrating the `@convex-dev/persistent-text-streaming` component with Svelte bindings.
+
+## Setup
+
+1. Make sure you have the Convex backend running (shared with the React example):
+
+```bash
+cd ../example
+npx convex dev
+```
+
+2. Install dependencies and run the Svelte example:
+
+```bash
+bun install
+bun run dev
+```
+
+## Features
+
+- Real-time chat interface with AI responses
+- HTTP streaming for immediate token display
+- Convex sync as persistent fallback for page reloads
+- Svelte 5 runes for reactivity
+
+## Key Files
+
+- `src/App.svelte` - Main app component with Convex setup
+- `src/components/ChatWindow.svelte` - Chat interface
+- `src/components/MessageItem.svelte` - Individual message display
+- `src/components/ServerMessage.svelte` - Server response with streaming using `useStream`
+
+## Usage
+
+The `useStream` hook from `@convex-dev/persistent-text-streaming/svelte` provides:
+
+```svelte
+<script lang="ts">
+  import { useStream } from "@convex-dev/persistent-text-streaming/svelte";
+
+  let { isDriven, streamId } = $props();
+
+  const stream = useStream(
+    api.streaming.getStreamBody,  // Query function reference
+    new URL("/api/stream"),        // HTTP streaming endpoint
+    () => isDriven,                // Getter for whether this client drives the stream
+    () => streamId,                // Getter for stream ID
+  );
+
+  // Reactive properties
+  // stream.text - Current text content
+  // stream.status - "pending" | "streaming" | "done" | "error"
+</script>
+```
+
+Note: The `getDriven` and `getStreamId` parameters are getter functions (not values) to enable Svelte's reactivity system to track changes.
+
diff --git a/example-svelte/bun.lock b/example-svelte/bun.lock
diff --git a/example-svelte/convex b/example-svelte/convex
@@ -0,0 +1 @@
+../example/convex
diff --git a/example-svelte/index.html b/example-svelte/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Convex Chat Example (Svelte)</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+
diff --git a/example-svelte/package.json b/example-svelte/package.json
@@ -0,0 +1,28 @@
+{
+  "name": "persistent-text-streaming-svelte-example",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^5.0.3",
+    "@tailwindcss/vite": "^4.1.0",
+    "svelte": "^5.33.0",
+    "tailwindcss": "^4.1.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.2.0"
+  },
+  "dependencies": {
+    "@convex-dev/persistent-text-streaming": "file:..",
+    "clsx": "^2.1.1",
+    "convex": "^1.29.0",
+    "convex-svelte": "^0.0.12",
+    "marked": "^15.0.0",
+    "tailwind-merge": "^3.3.0"
+  }
+}
+
diff --git a/example-svelte/src/App.svelte b/example-svelte/src/App.svelte
@@ -0,0 +1,12 @@
+<script lang="ts">
+  import { setupConvex } from "convex-svelte";
+  import ChatWindow from "./components/ChatWindow.svelte";
+
+  const convexUrl = import.meta.env.VITE_CONVEX_URL;
+  setupConvex(convexUrl);
+</script>
+
+<main class="flex min-h-screen flex-col">
+  <ChatWindow />
+</main>
+
diff --git a/example-svelte/src/app.css b/example-svelte/src/app.css
@@ -0,0 +1,17 @@
+@import "tailwindcss";
+
+:root {
+  font-family: Inter, system-ui, Avenir, Helvetica, Arial, sans-serif;
+  line-height: 1.5;
+  font-weight: 400;
+
+  color-scheme: light dark;
+  color: rgba(255, 255, 255, 0.87);
+  background-color: #242424;
+
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
diff --git a/example-svelte/src/components/ChatWindow.svelte b/example-svelte/src/components/ChatWindow.svelte
@@ -0,0 +1,133 @@
+<script lang="ts">
+  import { useQuery, useConvexClient } from "convex-svelte";
+  import MessageItem from "./MessageItem.svelte";
+  import ServerMessage from "./ServerMessage.svelte";
+  import { api } from "../../convex/_generated/api";
+  import type { Id } from "../../convex/_generated/dataModel";
+
+  const client = useConvexClient();
+  const messages = useQuery(api.messages.listMessages, () => ({}));
+
+  // Use a plain object for better Svelte reactivity tracking
+  let drivenIds = $state<Record<string, boolean>>({});
+  let isStreaming = $state(false);
+  let inputValue = $state("");
+  let messagesEndRef = $state<HTMLDivElement | null>(null);
+  let inputRef = $state<HTMLInputElement | null>(null);
+
+  function isDriven(id: string): boolean {
+    return drivenIds[id] === true;
+  }
+
+  function focusInput() {
+    inputRef?.focus();
+  }
+
+  function scrollToBottom(behavior: ScrollBehavior = "smooth") {
+    messagesEndRef?.scrollIntoView({ behavior });
+  }
+
+  // Scroll to bottom when window resizes
+  $effect(() => {
+    function handleResize() {
+      scrollToBottom();
+    }
+    window.addEventListener("resize", handleResize);
+    return () => window.removeEventListener("resize", handleResize);
+  });
+
+  async function handleSubmit(e: SubmitEvent) {
+    e.preventDefault();
+    if (!inputValue.trim()) return;
+
+    const prompt = inputValue;
+    inputValue = "";
+
+    const chatId: Id<"userMessages"> = await client.mutation(
+      api.messages.sendMessage,
+      { prompt },
+    );
+
+    // Use object spread to trigger reactivity
+    drivenIds = { ...drivenIds, [chatId]: true };
+    isStreaming = true;
+  }
+
+  async function clearAllMessages() {
+    await client.mutation(api.messages.clearMessages, {});
+    inputValue = "";
+    isStreaming = false;
+    focusInput();
+  }
+
+  function stopStreaming() {
+    isStreaming = false;
+    focusInput();
+  }
+</script>
+
+<div class="flex-1 flex flex-col h-full bg-white">
+  <div class="flex-1 overflow-y-auto py-6 px-4 md:px-8 lg:px-12">
+    <div class="w-full max-w-5xl mx-auto space-y-6">
+      {#if messages.isLoading}
+        <div class="text-center text-gray-500">Loading messages...</div>
+      {:else if messages.error}
+        <div class="text-center text-red-500">
+          Error loading messages: {messages.error.message}
+        </div>
+      {:else if messages.data && messages.data.length === 0}
+        <div class="text-center text-gray-500">
+          No messages yet. Start the conversation!
+        </div>
+      {:else if messages.data}
+        {#each messages.data as message (message._id)}
+          <MessageItem {message} isUser={true}>
+            {message.prompt}
+          </MessageItem>
+          <MessageItem {message} isUser={false}>
+            <ServerMessage
+              {message}
+              isDriven={isDriven(message._id)}
+              {stopStreaming}
+              {scrollToBottom}
+            />
+          </MessageItem>
+        {/each}
+      {/if}
+      <div bind:this={messagesEndRef}></div>
+    </div>
+  </div>
+
+  <div class="border-t border-gray-200 py-6 px-4 md:px-8 lg:px-12">
+    <form onsubmit={handleSubmit} class="w-full max-w-5xl mx-auto">
+      <div class="flex items-center gap-3">
+        <input
+          bind:this={inputRef}
+          bind:value={inputValue}
+          placeholder="Type your message..."
+          disabled={isStreaming}
+          class="flex-1 p-4 border border-gray-300 rounded-lg focus:border-blue-500 focus:ring-1 focus:ring-blue-500 outline-none text-base text-black"
+        />
+        <button
+          type="submit"
+          disabled={!inputValue.trim() || isStreaming}
+          class="px-8 py-4 bg-blue-600 text-white rounded-lg hover:bg-blue-700 transition-colors disabled:bg-gray-400 disabled:text-gray-200 font-medium"
+        >
+          Send
+        </button>
+        <button
+          type="button"
+          disabled={!messages.data || messages.data.length < 2 || isStreaming}
+          onclick={clearAllMessages}
+          class="px-8 py-4 bg-red-600 text-white rounded-lg hover:bg-red-700 transition-colors disabled:bg-gray-400 disabled:text-gray-200 font-medium"
+        >
+          Clear Chat
+        </button>
+      </div>
+      {#if isStreaming}
+        <div class="text-xs text-gray-500 mt-2">AI is responding...</div>
+      {/if}
+    </form>
+  </div>
+</div>
+
diff --git a/example-svelte/src/components/MessageItem.svelte b/example-svelte/src/components/MessageItem.svelte
@@ -0,0 +1,53 @@
+<script lang="ts">
+  import type { Doc } from "../../convex/_generated/dataModel";
+  import type { Snippet } from "svelte";
+
+  let {
+    message,
+    isUser,
+    children,
+  }: {
+    message: Doc<"userMessages">;
+    isUser: boolean;
+    children: Snippet;
+  } = $props();
+
+  const formattedDate = $derived(
+    new Date(message._creationTime).toLocaleDateString(),
+  );
+  const formattedTime = $derived(
+    new Date(message._creationTime).toLocaleTimeString(),
+  );
+</script>
+
+{#if isUser}
+  <div class="flex items-center gap-4 my-4">
+    <div class="flex-1 h-px bg-gray-200"></div>
+    <div class="text-sm text-gray-500">
+      {formattedDate}
+      {formattedTime}
+    </div>
+    <div class="flex-1 h-px bg-gray-200"></div>
+  </div>
+{/if}
+
+<div class="flex gap-4 {isUser ? 'justify-end' : 'justify-start'}">
+  <div class="flex gap-4 max-w-[95%] md:max-w-[85%] {isUser && 'flex-row-reverse'}">
+    <div
+      class="flex h-10 w-10 shrink-0 items-center justify-center rounded-full {isUser
+        ? 'bg-blue-600 text-white'
+        : 'bg-gray-300 text-gray-700'} font-medium text-sm"
+    >
+      {isUser ? "U" : "AI"}
+    </div>
+
+    <div
+      class="rounded-lg px-5 py-4 text-base {isUser
+        ? 'bg-blue-600 text-white'
+        : 'bg-gray-100 border border-gray-200 text-gray-900'}"
+    >
+      {@render children()}
+    </div>
+  </div>
+</div>
+
diff --git a/example-svelte/src/components/ServerMessage.svelte b/example-svelte/src/components/ServerMessage.svelte
@@ -0,0 +1,59 @@
+<script lang="ts">
+  import { getConvexSiteUrl } from "$lib/utils";
+  import type { StreamId } from "@convex-dev/persistent-text-streaming";
+  import { useStream } from "@convex-dev/persistent-text-streaming/svelte";
+  import { api } from "../../convex/_generated/api";
+  import type { Doc } from "../../convex/_generated/dataModel";
+  import { marked } from "marked";
+
+  let {
+    message,
+    isDriven,
+    stopStreaming,
+    scrollToBottom,
+  }: {
+    message: Doc<"userMessages">;
+    isDriven: boolean;
+    stopStreaming: () => void;
+    scrollToBottom: () => void;
+  } = $props();
+
+  const stream = useStream(
+    api.streaming.getStreamBody,
+    new URL(`${getConvexSiteUrl()}/chat-stream`),
+    () => isDriven,
+    () => message.responseStreamId as StreamId,
+  );
+
+  const isCurrentlyStreaming = $derived(
+    isDriven && (stream.status === "pending" || stream.status === "streaming"),
+  );
+
+  // Stop streaming when done
+  $effect(() => {
+    if (!isDriven) return;
+    if (isCurrentlyStreaming) return;
+    stopStreaming();
+  });
+
+  // Scroll to bottom when text updates
+  $effect(() => {
+    if (!stream.text) return;
+    scrollToBottom();
+  });
+
+  // Parse markdown
+  const htmlContent = $derived(
+    stream.text ? marked.parse(stream.text) : "<p>Thinking...</p>",
+  );
+</script>
+
+<div class="md-answer prose prose-sm max-w-none">
+  {#await htmlContent then html}
+    {@html html}
+  {/await}
+  {#if stream.status === "error"}
+    <div class="text-red-500 mt-2">Error loading response</div>
+  {/if}
+</div>
+
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		../example/convex
Copy link coderabbitai bot Nov 26, 2025 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. ⚠️ Potential issue \| 🟡 Minor 🧩 Analysis chain Script executed: #!/bin/bash # Check if the symlink exists and its target echo "=== Checking symlink ===" ls -la example-svelte/convex 2>/dev/null \|\| echo "Symlink not found" echo "" echo "=== Git symlink configuration ===" git config --get core.symlinks echo "" echo "=== Verify target directory exists ===" if [ -d "example/convex" ]; then echo "Target directory exists" echo "Target contents:" ls example/convex/ 2>/dev/null \|\| echo "Cannot list target" else echo "Target directory 'example/convex' not found" fi echo "" echo "=== Check Git tracking of symlink ===" git ls-files example-svelte/convex echo "" echo "=== Check if example-svelte directory exists ===" ls -la example-svelte/ 2>/dev/null \| head -20 Repository: get-convex/persistent-text-streaming <shell_result> Repository: get-convex/persistent-text-streaming Script execution failed with unrecoverable error: [CAPABILITY:RUN_SHELL_SCRIPT] Failed to clone repository get-convex/persistent-text-streaming: Clone operation failed </shell_result> symlinks git repository cross-platform windows core.symlinks <web_search_result> Short answer Git stores symlinks in the repo as special blob entries; whether the working tree contains real OS symlinks is controlled by core.symlinks. [1] On Windows Git will often set core.symlinks = false for a new repo (or a client may ignore your global setting), so symlinks are checked out as small text files containing the link target. [1][2][3] What to do (practical steps) Ensure Windows allows creating symlinks: Enable Developer Mode (Windows Settings → For developers) or use an elevated prompt on older Windows. [2][3] Install / re-install Git for Windows with the "Enable symbolic links" option (if present) and/or use the system Git (not an embedded Git in a GUI) so symlink support is available. [2] In the repo set core.symlinks = true (global or per-repo): git config --global core.symlinks true or inside the repo: git config core.symlinks true If you change core.symlinks after clone, recreate the worktree links: git reset --hard (or reclone after changing the setting) — some clients (e.g., GitHub Desktop) may ignore global settings when creating a repo, so reclone with the correct Git/client is easiest. [2][3] Notes / caveats core.symlinks is both a request and a cached capability flag: git-clone/git-init probe the environment and may write symlinks=false into the repo config if symlinks look unsupported. Manually overriding may be necessary but some GUIs still create repos with symlinks disabled. [1][2] If teammates use different OSes or clients, prefer avoiding repository symlink reliance when possible (or document/standardize the required Windows settings). [1][3] Sources git-config (core.symlinks) documentation. [1] Explanation and behavior on Windows / why clone may set symlinks=false (Stack Overflow). [2] Reports of GUI clients ignoring global symlink settings (GitHub Desktop issues / discussions). [3] </web_search_result> Symlink for sharing Convex backend — works but requires cross-platform setup documentation. This symlink allows the Svelte example to reuse the existing Convex backend from the React example, avoiding duplication. However, symlinks have documented cross-platform issues: On Windows, Git often defaults to `core.symlinks=false`, causing symlinks to be checked out as text files rather than actual symlinks GitHub Desktop and some other GUI clients ignore global symlink settings and may create repositories with symlink support disabled Team members on different operating systems may have inconsistent experiences unless setup is standardized Recommendation: Document the symlink requirement in a setup guide or `README`, specifying that Windows developers should enable Developer Mode and configure `git config core.symlinks true`, or consider providing a non-symlink alternative (copy or build step) for better cross-platform compatibility. 🤖 Prompt for AI Agents In example-svelte/convex around line 1, the repository uses a filesystem symlink to ../example/convex which can break on Windows and other environments; update project setup to avoid platform inconsistencies by either (a) adding clear documentation in example-svelte/README.md indicating the symlink requirement and exact steps for Windows (enable Developer Mode and run git config core.symlinks true) and any GUI client caveats, or (b) replace the symlink with a cross-platform alternative such as copying the Convex backend into the example during a setup script or adding a build step that links/duplicates the backend content at install time; implement one of these options and ensure README lists the chosen approach and commands to reproduce the link locally.