# Set up super-assist in an app

You are adding super-assist to the user's React app: a ready-made assistant panel beside every page, which reads the open page and acts through what the page **lends** it. The assistant runs on Super Assist, at superassist.app: a project there holds the agent that answers, and the app connects to it with the project's publishable key. The app needs no backend for it. The work is done when one page of their app is assisted, the app typechecks and builds, and the user has the commands to see it working.

Every docs page named below is Markdown. Fetch a step's page before writing its code.

## Step 1: Read the app, then agree a plan

Look before asking. From the repository, find:

1. The framework, router and package manager. React and React DOM must be 19.3 or newer.
2. How the framework exposes a public environment variable to the browser, such as `NEXT_PUBLIC_` for Next.js or `VITE_` for Vite, and the env file it reads, such as `.env.local`.
3. Whether the app has signed-in users, and where the client reads the current user's id.
4. Any chat UI the app has today, which the panel replaces.
5. The page to assist first: one with a list or a form and buttons that change something, such as orders, tickets or settings.

Ask the user only what the repository leaves open, in one round of at most three questions, and treat their answers as binding. Always ask whether they already have a Super Assist project and its publishable key, which starts with `pk_`. For what stays unanswered, take the defaults: the floating panel, the busiest list page, and a visitor for every end user.

Write the plan in your reply before changing files:

- App: `<framework, router, package manager>`
- Key: `<PUBLIC_ENV_VAR>` in `<env file>`, and whether the user has a project yet
- User: `visitor`, or `<where the client reads the signed-in user's id>`
- Panel: `floating`, `sheet` or `embedded`
- First page: `<route>`, what its content returns, and the action it lends

Done when every line is filled from the repository or the user's answer.

## Step 2: Install

With the app's package manager, install the one package: `npm install @super-assist/react`. It brings the panel, its styles and the runtime, with everything the runtime needs.

Done when `package.json` has `@super-assist/react`.

## Step 3: Get the project ready

When the user has no project yet, ask once whether you should create the agent and the project through the Super Assist API and draft journeys. On a yes, follow https://superassist.app/how-to/set-up-through-the-api.md: install or create the agent, create the project and write its publishable key into the env file under the plan's variable. Post the pages and draft the journeys after step 5, once the pages lend their actions. Call the API in one of two ways:

- **The MCP server**, first. When Super Assist's `search` and `execute` tools are in your tool list, `execute` calls the API as the user, in the organization they picked at sign-in. When they aren't, ask the user to connect it, as https://superassist.app/how-to/give-agents-the-docs.md shows: in Claude Code, the Super Assist plugin and `/mcp`; in Codex, Cursor or VS Code, the server at `https://superassist.app/mcp`. Go on once the tools are there.
- **An organization key with curl**, when the user prefers it or their agent can't connect: the user, an owner or admin of their organization, creates the key on the API keys page and pastes it into `.env.local`.

On a no, hand them steps 1 to 3 of https://superassist.app/tutorials/add-an-assistant.md, which sign up, create an agent, create a project, and copy its publishable key from the project's page. For a support agent that answers from their help center, point them at **Install a template** on the Agents page and https://superassist.app/dashboard/templates.md, which names the placeholders to replace and the knowledge base to attach. They put the key in the env file under the plan's variable.

Either way, the user signs up at superassist.app first. Agents answer on the organization's AI spend: the Pro plan includes some every month, and the Free plan runs agents only on credits bought in Billing, so tell them about the plan too.

A new project accepts `http://localhost:3000` and `http://localhost:5173`. When the app's dev server runs on another origin, pass it in `allowedOrigins` as you create the project, or the user adds it under **Allowed origins** on the project's page in the dashboard.

Done when the publishable key is in the env file, or you've handed the user these steps for the hand-off.

## Step 4: Add the runtime, the provider and the panel

In one client component, such as `app/assistant.tsx`, that takes `children`:

1. Import the styles once: `import "@super-assist/react/styles.css";`.
2. Create the runtime with `useAssistedRuntime` from `@super-assist/react`, passing the publishable key from the plan's variable as `key`. When the app has signed-in users, pass `user` with their id, as https://superassist.app/how-to/use-the-hosted-runtime.md shows.
3. Render `<AssistedProvider runtime={runtime}>` around the children, and `<AssistedPanel mode="floating" threads />` inside it after them. For the sheet or embedded modes, follow https://superassist.app/how-to/place-the-panel.md.
4. In the root layout, render `<Assistant>{children}</Assistant>` inside `<body>`.

Remove the app's previous chat UI when the panel replaces it.

Done when every page renders inside `AssistedProvider` with the panel beside it.

## Step 5: Make the first page assisted

Follow https://superassist.app/how-to/make-a-page-assisted.md and https://superassist.app/how-to/add-actions.md on the plan's page:

1. Wrap the page's content in `AssistedPage` inside a client component, with `name` (what the user calls the page), `instructions` (how to work there, naming its actions) and `content={() => data}` returning the ids and values the page shows. Add two `starters` the page can answer.
2. Wrap one button in `AssistedAction` with a `name` and a `label` saying what pressing it does. Rows share one `name`, each with its own `id`.
3. Mark the action `consequential` when its effect is the user's to own: paying, refunding, deleting, sending. When unsure, leave it plain and name it in the hand-off as the user's choice.

Done when the page lends its content and at least one action.

## Step 6: Validate

1. Run the app's typecheck script, else `npx tsc --noEmit`, and its build, and fix what fails.
2. When you can run the app (it needs no working key for this), follow https://superassist.app/how-to/mount-devtools.md: open the page and check the **Assisted pages** tab. It shows the page's note, `get_page_content`'s answer, and the action with its ids. Type `/` in the panel's input: the page's action is listed.

When you cannot run the app, say so and hand these checks to the user in step 7.

Done when the typecheck and the build pass.

## Step 7: Hand off

End with a short checklist:

- The plan from step 1, as built, and the files changed.
- The typecheck and build results, and the devtools check if you ran it.
- What step 3 leaves the user: the project steps when you didn't create it, or the placeholders left and the journey drafts to publish when you did.
- The user's next commands: set `<PUBLIC_ENV_VAR>` in the env file, start the dev server, open the page, ask a question its content answers, then ask for the action. When the panel stays silent, the browser console shows why Super Assist refused the connection.
- The dashboard side, once the panel works: a knowledge base for grounded answers (https://superassist.app/dashboard/knowledge-bases.md) and the Support email in Settings so handoffs reach a person (https://superassist.app/dashboard/handoffs.md). The panel asks whether an issue is resolved and offers a person on its own. Nothing in the app changes for any of it.
- For later work: the Super Assist plugin in Claude Code (`/plugin marketplace add mertdogar/super-assist-templates`, then `/plugin install super-assist@super-assist`), or `npx skills add mertdogar/super-assist-templates` in other agents, gives their coding agent the rules for pages, fields, tools and consequential actions, and a `sync` command that keeps the project's page catalog matching the code.

## Rules

- Code references the publishable key's environment variable, never its value. Only the env file holds the value: the user's to set, or yours when you created the project.
- The organization key stays in `.env.local`: read it inside each command, as the setup page shows, and never print it.
- Keep one runtime: change the layout the app already has, and replace its previous chat UI rather than running both.
- Every docs page is Markdown at its URL with `.md`, indexed at https://superassist.app/llms.txt.