Lyba RX overview

Lyba RX adds Lyba's client review-and-approval layer to a React app using the deploy-preview model: clients pin comments on your real preview build and give a timestamped sign-off bound to a commit. No client accounts, no proxy.

Two packages and a hosted backend

You install two pieces. The hosted backend you don't.

• @lyba/react — the browser-side half. Your app renders <LybaReview /> on preview builds, and the overlay activates only when a reviewer arrives with a review link. Zero footprint otherwise.
• @lyba/cli — the automation half. It runs in CI after each preview deploy, tells Lyba which preview URL and commit SHA are under review, and prints a client-safe review link.
• Lyba backend + dashboard — validates your API key, stores comments, issues the signed approval receipt, and is where your team triages and approves.

Your agency account connects the workflow: the dashboard uses your signed-in session, and the CLI uses an agency API key. Approval receipts come from Lyba's backend, not from the browser package.

CI builds a preview  ─▶  @lyba/cli creates a review session (preview URL + commit SHA)
                                     │
                                     ▼
                         Review link  ─▶  client opens the preview
                                     │
                    @lyba/react overlay activates (preview + token only)
                                     │
              client pins DOM-anchored comments  ─▶  studio triages in the dashboard
                                     │
                    all resolved  ─▶  client signs off  ─▶  receipt bound to the commit SHA

When to use RX

Use @lyba/react for React apps that have deploy previews, for example:

• Next.js apps on Vercel
• Vite/React apps on Vercel, Netlify, or Cloudflare Pages
• React apps where each PR or branch deploy has a stable preview URL

If your site is built in Framer, use the Lyba Framer plugin instead. The Framer plugin injects the same overlay into the published Framer site, so you do not install @lyba/react there.

What you need

• A Lyba agency account.
• An agency API key from Dashboard → Settings → API keys, for CI automation with @lyba/cli.
• A React app that can render one client component near the root.
• A deploy-preview workflow where CI can run npx @lyba/cli session create after the preview URL exists.

The widget alone does not create review sessions. It only knows how to activate an existing review session when a client opens a Lyba review link. Equally, the CLI does not inject the overlay: if @lyba/react is not installed in the app, the review link can open the preview but no Lyba UI will appear.

Start in the dashboard

Open Dashboard → Set up React (/dashboard/setup/react). The guided flow:

1. Chooses Next.js App Router or Vite/React and your preview host, then creates or reuses a React project using its repository/project key.
2. Gives you copyable installation instructions and an explicit preview-only build flag. An unset flag leaves the overlay disabled.
3. Creates a review from a deployed HTTPS preview URL and its full commit SHA. This step requires no API key or CI configuration and sends no client invites.
4. Opens the review link and checks for a new comment on this build. Carried feedback from a previous round does not count as installation verification.

Once a comment arrives, resolve your test comment in the review dashboard and share the durable link with your client. The final step also includes optional CLI instructions for automating future deployments. Keep the same project key in CI so its reviews appear in the project you set up.

You can revisit the guide from a React project's Setup guide link. Verification checks saved comments via the authenticated Lyba API; it does not crawl or inspect the preview remotely.

How review sessions work

A review session is created server-side by Lyba. For React projects, a session is bound to:

• the preview URL clients should review
• the commit SHA being reviewed
• the git branch/ref, provider, and PR number when available
• optional reviewer email addresses

The widget does not decide which commit is approved. The session created by @lyba/cli does. That is why the CLI should run after the preview deploy, using the real preview URL and commit SHA.

When the client opens the review link:

1. Lyba redirects them to the preview URL with a short-lived review token.
2. <LybaReview /> sees the token and activates the overlay.
3. The client pins comments on the live DOM.
4. Each pin captures page URL, viewport width, breakpoint, selector, offset, and fallback position.
5. Your team handles comments in the Lyba dashboard.
6. Once every comment is resolved, your team can request approval.
7. The client signs off and Lyba records an immutable approval receipt.

No client account is required. Normal visitors, including normal preview visitors, do not see Lyba unless they open a review link. See Review links for how the links themselves work.

Triage and approval

In the dashboard session view, your team:

• Sees every comment with its page, breakpoint, and pin, plus the preview build (commit / branch / provider / PR).
• Resolves, marks needs discussion, or replies to each comment.
• Optionally pushes a comment to Linear ("Create issue").
• Requests approval — enabled once every comment is resolved. This emails the client a sign-off link.

When the client approves, Lyba writes an immutable approval receipt with a SHA-256 checksum, bound to the session's commit SHA. That receipt is the artifact — valid whether or not the client ever created an account.

Need another round? Start next round clones the page scope and carries every unresolved comment into a fresh session.

After a client approves, Lyba may email them an optional magic link to save their identity (no password) so future rounds remember them. Claiming only enriches attribution; the approval receipt is equally valid with or without it.

Slack notifications and Linear issues are configured per project in Dashboard → Settings → Integrations. See Integrations.

Projects and sessions

For React projects, Lyba uses:

• Project: long-lived app or repo, keyed by --project.
• Session: one review round for one preview deploy.

Run session create for every preview deploy you want reviewed. Reusing one old review link across unrelated deploys weakens commit binding and can make DOM anchors less reliable.

Anchoring behavior

Pins anchor to real DOM elements, not screenshots. On creation, Lyba stores a resilient selector plus the click offset inside the target element. On reload, the overlay tries to re-resolve that selector and place the pin back on the live element.

For best results:

• Add stable id, data-testid, or data-lyba-id attributes to important sections, CTAs, pricing cards, forms, and hero elements.
• Avoid generating unstable class names for elements clients are likely to comment on, unless those elements also have stable data attributes.
• Create a new review session for each deploy instead of reusing an old review link across unrelated builds.

If a target element cannot be found on a later build, Lyba keeps the comment and marks the pin as orphaned instead of losing it.

Next steps

• Quickstart: Next.js App Router
• Quickstart: Vite / React
• Choosing the enabled gate — keep the overlay off in production.
• Create sessions from CI — automate a review session per preview deploy.
• Content Security Policy and Troubleshooting