2-minute setup

Install PlotUI

One command. Works with Next.js, Vite, Remix, and CRA. No config files. No API keys in source code.

1

One command (recommended)

Terminal
npx plotui-cli init
✓Asks for your API key once
✓Auto-detects Next.js / Vite / Remix
✓Injects the widget script tag into your layout
✓Scans your codebase and generates the knowledge graph
✓Opens your dashboard automatically
$ npx plotui-cli init
╔═══════════════════════════════════╗
║ PlotUI — Quick Setup ║
╚═══════════════════════════════════╝
› Paste your PlotUI API key: pk_live_••••••••
✓ API key verified — MyApp plan: free
✓ Framework: nextjs-app
✓ Injected into app/layout.tsx
✓ API key saved to .env.local
✓ 34 pages scanned and mapped
✓ PlotUI is set up!
Dashboard: https://www.plotui.com/dashboard/graph
or
2

Paste into Lovable / Bolt / Cursor / Claude

Copy this prompt and paste it into your AI coding tool. It will handle the injection automatically. Replace YOUR_ORG_ID with the value from your dashboard → Settings.

AI Prompt — copy and paste into Lovable, Bolt, Cursor, or Claude
You are installing PlotUI — an AI support-chat widget — into this codebase.
Do all four steps below in order. Do NOT ask me for confirmation between steps.

═══ PREREQUISITES ═══
The user must give you these two values (ask once at the start if missing):
  • PLOTUI_ORG_ID  — looks like a UUID, e.g. 7c2a1e4f-...
  • PLOTUI_API_KEY — starts with "plotui_"
Both come from https://www.plotui.com/dashboard/settings

═══ STEP 1 — Embed the widget script ═══
Find the root layout file. Search this order, use the first that exists:
  1. app/layout.tsx     (Next.js App Router)
  2. src/app/layout.tsx (Next.js App Router in src/)
  3. pages/_document.tsx (Next.js Pages Router)
  4. index.html         (Vite / CRA / static)

Add this script tag as the LAST child of <body>:

<script src="https://www.plotui.com/widget.js" data-org="PASTE_ORG_ID_HERE" async></script>

In Next.js layout.tsx, use the <Script> component from next/script with strategy="lazyOnload" if you prefer, but a plain <script> in <body> works too.

═══ STEP 2 — Save the API key ═══
Add this line to .env.local (create the file if it doesn't exist):

PLOTUI_API_KEY=plotui_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

If .env.local is gitignored already, good. If not, add it to .gitignore.

═══ STEP 3 — Run the scanner ═══
Run this command from the project root (PlotUI auto-detects subdirectory apps in monorepos and auto-loads .env.local):

npx plotui-cli@latest scan --yes

Expected output:
  ✓ Knowledge graph generated and saved!
  Pages: N nodes mapped

If it errors with "Framework not detected", the suggestion line tells you which subdirectory to point at — re-run with --dir.

═══ STEP 4 — Tell the user the final manual step ═══
Print this message to the user (DO NOT do it for them — they must approve in the dashboard):

  PlotUI is installed. One last step:
  → Open https://www.plotui.com/dashboard/review
  → Click "Publish All" to make the widget live for your users
  
  After that, the widget bubble appears in the bottom-right of every page.
  Test it by asking "How do I sign up?" or any feature question.

═══ NOTES ═══
• Source code is never stored by PlotUI — only page structure (route names, button labels, headings) is sent to Gemini for description generation.
• Re-run "npx plotui-cli@latest scan" any time you ship new pages — only changed files trigger updates (hash-based incremental scan).
• Free tier: 100 queries/month, "Powered by PlotUI" badge. Paid tiers remove the badge.
LovableBoltCursorClaudev0Windsurf
3

Manual (3 steps)

Step 1 — Add the widget to your layout (before </body>)

<script
  src="https://www.plotui.com/widget.js"
  data-org="YOUR_ORG_ID"
  async
></script>

Step 2 — Scan your codebase

npx plotui-cli@latest scan --api-key YOUR_API_KEY

Monorepo? If your Next.js app lives in a subdirectory, run from that folder or pass --dir ./apps/web.

Step 3 — Approve nodes in the Review queue

New nodes start as draft for safety. Open Dashboard → Review, check the AI descriptions, and click Publish All (or per-node). Re-scans of unchanged pages skip the queue automatically.

Where to find your keys

Org IDDashboard → Settings → Embed Code → data-org="..."
API KeyDashboard → Settings → API Key tab
Create free account →

Re-scan on every deploy (optional)

Add this to your GitHub Actions workflow so the knowledge graph stays in sync with your codebase automatically.

.github/workflows/plotui.yml
- name: Sync PlotUI knowledge graph
  run: npx plotui-cli@latest scan --api-key ${{ secrets.PLOTUI_API_KEY }} --yes