Skip to main content

Install by pull request

This is one of the two ways to install. On the workspace's Overview or Install tab, choose Connect GitHub and pick the repository. Frankie's install agent reads the repository and opens one draft pull request that adds the chat to your React app and the sign-in token route to its backend. You review it like any other change, and nothing ships until you merge.

Prefer to work in your own editor? Your AI coding assistant can make the same change from one prompt.

What it works with​

  • Any React app and its backend: Next.js (App Router or Pages Router), a Vite or React SPA with an Express, Fastify, Hono or Nest backend, Remix or React Router, and backends in other languages (Python, Go, Ruby…). The token route goes into the backend you already have, in its language and framework.
  • Monorepos: if the repository has more than one app, the dashboard asks which one to install into.
  • Non-React frontends (Vue, Svelte, Angular, server-rendered HTML): the agent changes nothing and tells you the SDK is React-only, with your options.

Sign-in​

The agent wires POST /api/frankie/token to your app's existing sign-in: Auth.js / NextAuth, Clerk, Supabase, Firebase session cookies, or your own session code. It never invents a new auth system.

When it can't tell how your app identifies the signed-in user, it still writes the route, but the route answers 501 until you fill in one lookup. The pull request says so in its Needs you section: what it looked for, what it found, and the exact file to fill in. See The install agent couldn't wire sign-in.

The pull request is one step. For the full list, including variables, allowed sites and allowed actions, see the Go live checklist.

What the Product agent's pull request adds​

On a Next.js App Router app:

  • @frankieai/react in package.json, and jose when users sign in.
  • app/frankie/FrankieAgents.tsx (or src/app/frankie/…), mounted once in your root layout. It holds every agent (Product, Support and Docs) and shows each one only when its key is set, on its pages, and never over the full-page chat.
  • The full-page chat at /chat, or at /frankie/chat if /chat is taken.
  • /api/frankie/token, which tells Frankie who the signed-in user is (see Chat as the signed-in user).
  • /api/frankie/health, which reports only whether the variables are set, so the dashboard can show what your deployment has.
  • An OpenAPI draft of your API routes, public/frankie.openapi.json, connected for you. Every action starts switched off: allow them in Product agent → What may it do in your app?.
  • Blank entries in .env.example, and FRANKIE_SETUP.md with the remaining steps.

On any other React app, the pull request adds @frankieai/react to the frontend's package.json, mounts FrankieProvider and FrankieWidget once in the signed-in part of the app, adds POST /api/frankie/token to your backend (with a JWT library for its language), and adds blank entries for the variables to your example env file. Its description lists the files it changed and why.

The same pass reads your app's styles to suggest widget colors that match your brand. You accept or dismiss the suggestion under Widget.

Adding the Support and Docs agents​

If your app already has FrankieAgents.tsx, set the agent's key variable in your deployment and redeploy. That's it: no code change.

Otherwise, the agent's tab opens a small pull request that adds only the shared pieces: the package, FrankieAgents.tsx, the layout line, the health route and .env.example. These are identical in every agent's pull request, so you can open the Product, Support and Docs pull requests together and merge them in any order without conflicts. Use Use a different repository if, say, your docs live in a separate repo.

Apps installed with an earlier version keep working: the next install pull request moves them onto FrankieAgents.tsx, leaves the old module in place as an empty shim so its imports still resolve, and removes the old per-agent files.

Before you merge​

  • Read the Needs you section in the pull request description, and do what it lists. Most often that's connecting the token route to your sign-in.
  • Update the lockfile and commit it, because Frankie can't run your package manager remotely. Use npm install --package-lock-only, pnpm install --lockfile-only, yarn install or bun install. Otherwise npm ci fails in CI.
  • Set the variables for every environment you deploy (Preview and Production). See Environment variables.
  • Add every site the app runs on under Overview → Keys & settings → Allowed sites.
  • Make sure your CI checks pass. The dashboard shows them and offers to merge when they're green.

If a pull request was closed or failed, the agent's tab offers Open a new pull request. Frankie never overwrites a branch it didn't create; if one exists with other changes, it stops and tells you.