@lyba/react

v0.1.2

Published

2 months ago

Lyba client review & approval overlay for React deploy previews. Pin DOM-anchored comments and capture a timestamped sign-off, bound to the commit under review.

0High
0Medium
0Low

ovalaystudios

@lyba/react

Add Lyba's review overlay to a React app so clients can pin comments on real deploy previews and sign off on the exact commit they reviewed.

@lyba/react is the browser-side half of Lyba's React workflow:

Your app renders <LybaReview /> on preview builds.
CI runs @lyba/cli after each preview deploy to create a Lyba review session.
The CLI prints a review link such as https://lyba.io/r/abc123.
A client opens that link, lands on the preview, and the overlay activates.
Your team resolves comments in Lyba, requests approval, and gets an immutable approval receipt bound to the preview commit.

No client account is required. Normal visitors, including normal preview visitors, do not see Lyba unless they open a review link.

When To Use This Package

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 this package there.

What You Need

A Lyba agency account.
An agency API key from Dashboard -> Settings -> API keys.
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.

Install

npm install @lyba/react

Or:

pnpm add @lyba/react
yarn add @lyba/react

React 18 or React 19 must already be installed by your app.

Quickstart: Next.js App Router

Render <LybaReview /> once, high in the app tree. In Next.js App Router, that usually means your root layout.

// app/layout.tsx
import { LybaReview } from "@lyba/react";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <LybaReview enabled={process.env.NEXT_PUBLIC_VERCEL_ENV !== "production"} />
      </body>
    </html>
  );
}

Then create a review session from CI after the preview deploy:

npx @lyba/cli session create

The CLI creates the session, binds it to the preview URL and commit SHA, and prints the review link to share with the client.

Quickstart: Vite / React

Render the component once inside your app shell:

// src/App.tsx
import { LybaReview } from "@lyba/react";

export function App() {
  return (
    <>
      <YourApp />
      <LybaReview enabled={import.meta.env.VITE_VERCEL_ENV !== "production"} />
    </>
  );
}

If your host exposes VERCEL_ENV, CONTEXT, or a similar deploy variable without the VITE_ prefix, expose a public build variable yourself and gate on that. Browser code cannot read private CI environment variables at runtime.

The Mental Model

Lyba has three gates before anything appears:

Your enabled prop: this should be true only on preview builds.
Lyba's production veto: if the package confidently detects production, it refuses to render even if enabled is accidentally true.
The review token: the overlay mounts only when the URL contains a #lyba_token=... fragment from a Lyba review link.

That means:

Production builds should pass enabled={false}.
Preview builds can include the package safely.
Ordinary preview visitors still see nothing because they do not have a review token.
The token lives in the URL fragment, so it is not sent to your server as part of the request URL.

Choosing The `enabled` Gate

Pass enabled explicitly from your app. Do not rely on the package guessing your host environment unless you are experimenting locally.

| Host / framework | Recommended gate | |---|---| | Next.js on Vercel | enabled={process.env.NEXT_PUBLIC_VERCEL_ENV !== "production"} | | Vite on Vercel | enabled={import.meta.env.VITE_VERCEL_ENV !== "production"} | | Netlify | expose CONTEXT publicly and use enabled={publicContext !== "production"} | | Cloudflare Pages | expose the branch and use enabled={branch !== "main"} or your production branch | | Any host | gate on your own public preview flag, for example NEXT_PUBLIC_IS_PREVIEW === "true" |

The important rule: the expression must be false in production.

Content Security Policy

The overlay talks to Lyba's hosted API. If your app sends a strict CSP, add https://lyba.io to connect-src:

Content-Security-Policy: connect-src 'self' https://lyba.io;

If this is missing, the overlay may appear but fail token validation. In the browser console you will usually see a connect-src violation for https://lyba.io/api/v1/tokens-validate.

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:

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

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.

API Reference

`<LybaReview />`

<LybaReview enabled={isPreview} />

| Prop | Type | Default | Description | |---|---|---|---| | enabled | boolean | auto-detected | Hard gate. Pass this explicitly and make sure it is false on production. | | preview | Partial<PreviewContext> | auto-detected | Reserved/advisory preview context. The current session binding comes from the CLI-created server session. |

The component renders null in React. When all gates pass, it mounts Lyba's overlay into a shadow root and tears it down on unmount.

`detectPreview(env?)`

import { detectPreview } from "@lyba/react";

const preview = detectPreview({
  NEXT_PUBLIC_VERCEL_ENV: process.env.NEXT_PUBLIC_VERCEL_ENV,
  NEXT_PUBLIC_VERCEL_URL: process.env.NEXT_PUBLIC_VERCEL_URL,
});

detectPreview recognizes Vercel, Netlify, and Cloudflare Pages. Client-side environment variables must be passed in or inlined by your bundler. Private CI environment variables are not magically available in the browser.

Local Testing

You can test the integration before wiring CI:

Deploy a preview build with <LybaReview enabled={true} /> or with your preview gate evaluating true.

Run the CLI locally:

npx @lyba/cli session create \
  --project my-app \
  --project-name "My App" \
  --preview-url https://my-preview.example.com \
  --sha "$(git rev-parse HEAD)" \
  --ref "$(git branch --show-current)"

Open the printed review link.

Do not test by forcing enabled={true} in a production deployment. Use a preview deployment or a temporary non-production environment.

Common CI Pairing

Install the widget in the app, then add the CLI after the preview is available:

- name: Create Lyba review session
  id: lyba
  run: npx @lyba/cli session create
  env:
    LYBA_API_KEY: ${{ secrets.LYBA_API_KEY }}

- name: Share Lyba review link
  if: steps.lyba.outputs.review-url
  run: gh pr comment "$PR" --body "Review this preview in Lyba: ${{ steps.lyba.outputs.review-url }}"
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    PR: ${{ github.event.number }}

See the @lyba/cli README for full flag and provider examples.

Troubleshooting

| Symptom | Likely cause | Fix | |---|---|---| | Nothing appears when opening a review link | enabled is false on the preview build | Check the value your bundler inlined and use an explicit public preview env var. | | Nothing appears for normal visitors | Expected behavior | The overlay only mounts for users with a Lyba review token. | | Overlay appears on production | Production gate is wrong | Make enabled false for production and redeploy. | | Toolbar says the review link is invalid or expired | Token expired, session ended, or CSP blocked validation | Try the durable /r/<slug> review link again and check connect-src. | | Review link loses the token after preview auth | Preview protection redirected the user | Let the client access the preview without SSO, or use your host's preview bypass mechanism. | | Pins move after a redesign | DOM anchors changed | Add stable data-testid, data-lyba-id, or id hooks to important elements. | | Next.js import/build fails | Old package version | Use @lyba/[email protected] or newer. |

Security Notes

The agency API key never goes into the browser. It belongs in CI as LYBA_API_KEY for @lyba/cli.
Review links are anonymous capabilities. Treat them like client-facing review URLs.
The review token is sent to Lyba as an X-Lyba-Token header by the overlay, not as a server-visible query string.
Approval receipts are created by Lyba's backend, not by the browser package.

Related Docs

@lyba/cli: create review sessions from CI.
Lyba dashboard: manage sessions, comments, approvals, billing, and integrations.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@lyba/react

When To Use This Package

What You Need

Install

Quickstart: Next.js App Router

Quickstart: Vite / React

The Mental Model

Choosing The enabled Gate

Content Security Policy

How Review Sessions Work

Anchoring Behavior

API Reference

<LybaReview />

detectPreview(env?)

Local Testing

Common CI Pairing

Troubleshooting

Security Notes

Related Docs

Choosing The `enabled` Gate

`<LybaReview />`

`detectPreview(env?)`