> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add the Voiceflow widget to TanStack Start

> Install the supplied Voiceflow chat widget in TanStack Start, handle browser navigation and cleanup, and test a visitor conversation.

## Overview

Install the supplied embedded text-chat widget in TanStack Start for React. The root route renders server HTML; an Effect starts the widget in its empty container after hydration. This recipe installs an embedded panel for public support using an existing Voiceflow agent.

**Note:** 

**Building your own interface?** Framework-specific custom chat and voice guides are [planned](#custom-interface). Use [Chat agents](/docs/api-reference/agent-runtime/chat) and [Voice agents](/docs/api-reference/agent-runtime/voice) for their separate API contracts.

<a id="before-you-begin"></a>

## Before you begin

Prepare the published public agent and framework access.

| Requirement | What to prepare |
| --- | --- |
| Framework scope | TanStack Start 1.169.7 / Router 1.170.46 / React 19.3.1. The supplied starter targets the rendering model described above. |
| Agent owner | A [published support agent](/docs/guides/usecases/customer-service/build-faq-agent), its public widget project ID and the intended [Environment alias](/docs/documentation/deploy/environments/overview#aliases). |
| Widget configuration | Public API access already enabled; a Published release in that Environment. Disable file uploads in its published widget settings for this text-only recipe. |
| Site developer | Node.js 22.23.4 and npm; permission to edit and deploy the site and a staging origin. |
| Visitor test | A known question and expected answer, plus access to the resulting [Transcript](/docs/documentation/measure/transcripts). |

Obtain the project ID, alias and expected answer from the agent owner before editing the files. This starter uses the **public `verify.projectID` contract**; client-key, private/prototype and Private Cloud configurations require their own compatible installation. Keep framework application secrets, website login tokens and personal/service API keys on the server. See [TanStack Start project structure](https://tanstack.com/start/latest/docs/framework/react/build-from-scratch) for the platform behavior.

<a id="install-widget"></a>

## Install the widget

Configure and activate one browser-owned chat panel.

### 1. Download the complete starter

Download the [TanStack Start starter](/docs/examples/web-frameworks/tanstack-start.zip) and extract it. It includes the entry files, dependency locks and `src/widget/widget.js`, `widget-config.js` and `widget.d.ts`. The helper loads the supplied widget from its CDN; no Voiceflow npm package is needed.

For an existing site, copy only the widget integration and merge the placement below into your existing layout. Keep its other configuration. Remove any earlier Voiceflow snippet: this global widget API supports one active widget per document.

### 2. Choose the public project and Published release

Edit `src/widget/widget-config.js`:

```javascript
// Public identifiers for an existing public widget project, not API credentials.
export const widgetOptions = {
  verify: { projectID: "YOUR_PROJECT_ID" },
  url: "https://general-runtime.voiceflow.com",
  environmentID: "YOUR_ENVIRONMENT_ALIAS",
  versionVariant: "published",
  autostart: true,
  allowDangerousHTML: false,
  assistant: {
    type: "chat",
    persistence: "memory",
    enableVoiceInput: false,
    enableVoiceOutput: false,
    enableVoiceMode: false,
  },
};
```

Replace both `YOUR_` values with the supplied project ID and Environment alias. `environmentID` and `versionVariant: 'published'` select that Environment’s Published release; [legacy `versionID` compatibility](/docs/documentation/deploy/widget/web-chat-api#choosing-which-environment-the-widget-loads) is separate. Raw HTML is disabled while ordinary Markdown remains available.

### 3. Add the browser integration

Place the wrapper and helper files in `src/widget/`, then import it from `src/routes/__root.tsx` outside `<Outlet>`. Keep `HeadContent` and `Scripts` in the document. The starter uses the Start Vite plugin before the React plugin and generates its route tree when built.

`src/widget/VoiceflowChat.jsx`:

```jsx
import React, { useEffect, useRef } from "react";
import { mountWidget } from "./widget.js";

export default function VoiceflowChat() {
  const host = useRef(null);
  useEffect(() => mountWidget(host.current), []);
  return <div ref={host} aria-label="Support chat" />;
}
```

`src/routes/__root.tsx`:

```tsx
import {
  createRootRoute,
  HeadContent,
  Link,
  Outlet,
  Scripts,
} from "@tanstack/react-router";
import VoiceflowChat from "../widget/VoiceflowChat.jsx";
export const Route = createRootRoute({ component: Root });
function Root() {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>Support</title>
        <HeadContent />
      </head>
      <body>
        <nav>
          <Link to="/">Home</Link> <Link to="/about">About</Link>
        </nav>
        <Outlet />
        <VoiceflowChat />
        <Scripts />
      </body>
    </html>
  );
}
```

### 4. Run the local installation

From the extracted folder, install the pinned dependencies and start the app:

```bash
npm ci
npm run dev -- --port 5173
```

Open `http://localhost:5173`. One embedded chat panel should replace the loading message. The installed panel proves browser startup; complete the [visitor test](#test-conversation) to verify answers from your actual agent.

<a id="widget-lifecycle"></a>

## Handle widget lifetime and identity

Keep navigation, removal and guest conversations predictable.

Keep one wrapper in the root route through client navigation. A route loader or server function is not a browser mount point. Do not initialize the widget from loaders or create a new instance when search parameters change. An actual unmount invokes the Effect cleanup; a later mount receives a fresh inner target.

The helper serializes `load()` and disposal, reuses its own downloaded loader, and creates a fresh inner HTMLElement for each mount. It calls `destroy()` only for the widget it owns, then removes that target. Keep the outer container’s children under widget ownership.

| Event | Required behavior |
| --- | --- |
| Owner remains through navigation | Retain the mounted conversation; do not load or launch again. |
| Owner is removed while loading | Cancel startup where possible; finish an already-started load before cleanup and another mount. |
| Refresh or real remount | `persistence: 'memory'` starts a fresh guest conversation. |
| Logout/account switch | Remove the previous owner before support returns for the next account. Revoke your application/backend session separately. |

Browser `userID`, page context and launch values do not authenticate a customer. This public widget supplies no private-record authorization. Protected operations require a trusted backend boundary on every read/write, turn and resume; use the [canonical trusted-customer guidance](/docs/guides/integrations/crms/recognize-returning-customers#recognize-the-customer) before adding them. Widget `destroy()` does not delete transcripts or undo an in-flight business action.

### Use Solid instead of React

Keep the adaptation separate from the supplied starter.

TanStack Start also has a Solid implementation, but this download supplies a React component. A Solid integration needs its own browser mount/disposal hooks. Do not copy this React Effect into a Solid route; the installed widget contract remains the same.

<a id="test-conversation"></a>

## Test a visitor conversation

Verify the installed widget, replies and framework navigation.

Use a staging deployment with the final project/release configuration. If approved-domain restrictions are enabled, have the agent owner allow that origin. Check that the site’s content security policy permits the widget’s script, styles, fonts and runtime connections.

### 1. Open as a visitor

Open a fresh browser session at the staging URL. Accept any configured notice. Confirm one panel appears and that input, scrolling and keyboard behavior work at desktop and phone widths.

### 2. Check a question and follow-up

Send the prepared support question and a related follow-up. Both replies must match the intended agent/release and preserve the expected conversation context. Locate this exchange in the intended project’s [Transcripts](/docs/documentation/measure/transcripts).

### 3. Navigate and return

Use the starter’s **About** link and Back. Compare the result with [widget lifetime](#widget-lifecycle): the persistent owner should keep the same conversation. Open the nested route directly too. Check that navigation never leaves two active panels or a blank cached copy.

### 4. Check slow startup and recovery

Leave while the CDN/setup is pending, then return. There must be no overlapping load or detached-target error. Interrupt and restore the network. If a business action’s result is uncertain, check its outcome before retrying. Reload to confirm the fresh-start policy. If the site has sign-in, remove the widget during logout/account change and confirm that old messages do not return for another account.

### The panel stays blank

Trace the browser entry and configuration before changing the agent.

Confirm both placeholders were replaced and that the documented module/component actually executes in the browser. Check missing static files, blocked CDN/style/font/runtime requests, project public access, the Environment alias, its Published release and approved origins. The helper gives the target a visible height. After repairing a failed or partial load, reload the document; it does not automatically retry the SDK.

### Navigation duplicates or restarts support

Check layout placement, caching and cleanup ownership.

Remove other snippets and keep one owner. Compare your installation with the local [lifecycle instructions](#widget-lifecycle), including any framework cache or DOM-replacement behavior. A real unmount intentionally starts fresh with memory persistence. Preserve the helper’s cleanup rather than calling `load()` after every route event.

### The wrong agent answers

Check the published route with a fresh conversation.

Compare the installed project ID and Environment alias with the agent owner’s values. Confirm the known answer exists in that Published release; editing Draft does not change it. Use [Environment publishing](/docs/documentation/deploy/environments/publishing) before retesting.

<a id="release"></a>

## Release and maintain the installation

Publish the agent and website independently, then test production.

### 1. Publish the agent and deploy the application

Have the agent owner [publish the reviewed Environment](/docs/documentation/deploy/environments/publishing), including widget-setting changes. Run `npm run build`. Deploy `dist/client/`, `dist/server/`, `server.mjs` and the production dependencies together, or use the Start adapter supported by your host. The starter’s `npm run start` serves static client assets and forwards other requests to the built Start fetch handler.

### 2. Accept the production route

Open the actual HTTPS production URL and repeat the [visitor test](#test-conversation), including a direct nested-route request. Agent publication and site deployment are separate releases. Record the application commit, Environment release and observed widget version.

### Update, roll back or remove

Change the responsible release and repeat the visitor test.

Keep the last working application build and public widget configuration. The CDN URL moves independently of the framework lockfile, so test after widget updates. App rollback does not roll back the agent or delete transcripts. To remove support, remove its entry/component and deploy, retaining cleanup during removal. After any change, use the same visitor test.

<a id="custom-interface"></a>

## Custom interface guides

Planned framework guides for your own chat or voice UI.

Custom-interface walkthroughs for TanStack Start are **planned**, separate from the completed supplied-widget procedure.

| Planned guide | Available API reference |
| --- | --- |
| Build a custom chat interface | [Chat agents](/docs/api-reference/agent-runtime/chat) |
| Build a custom voice interface | [Voice agents](/docs/api-reference/agent-runtime/voice) |
