Menu
Start free trialLog in
Docs menu
Docs/Getting started

Projects, sessions and review links

Lyba organises review work into projects and review sessions. A client reaches a session through a review link: no client account is required, ever. This page describes the React deploy-preview workflow. If your site is built in Framer, the Lyba Framer plugin injects the same overlay into the published Framer site.

The review loop

text
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

Two pieces you install, one hosted backend you don't:

  • @lyba/react — the overlay component. Renders on preview builds only, and only when a reviewer arrives with a review link. See <LybaReview />.
  • @lyba/cli — creates a review session per preview deploy from CI and prints the reviewer link. See @lyba/cli commands.
  • Lyba backend and 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.

Projects

A project is the long-lived app or repo. For React projects it is keyed by --project: a stable project key, usually owner/repo or your site slug, defaulting to the repo slug the CLI detects in CI.

Creating a project is idempotent. Running lyba session create repeatedly for the same project reuses the project record and creates a new session for the new preview. If you set the project up through Dashboard → Set up React, keep the same project key in CI so its reviews appear in that project.

Review sessions

A session is one review round for one preview deploy. It is created server-side by Lyba, either by @lyba/cli from CI or by hand from the dashboard (Set up React, or project → New review session).

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 does. That is why the CLI should run after the preview deploy, using the real preview URL and commit SHA. The dashboard's general-purpose New review session form permits omitting the SHA, but an approval without one cannot identify a specific code revision.

Create one session per deploy. Comments are host-checked against the session's preview URL, and reusing one old review link across unrelated deploys weakens commit binding and can make DOM anchors less reliable.

Review links

Creating a session gives you two ways in:

text
✓ Lyba review session created for acme/web @ 8f4e2c9
  Review link: https://lyba.io/r/GtJY36X
  Direct link: https://acme-web-git-feature.vercel.app#lyba_token=...

The review link

The review link, usually https://lyba.io/r/<slug>, is the main link to share. It is durable and rotates a fresh, short-lived review token whenever opened: Lyba redirects the client to the session's preview URL with that token. In GitHub Actions the CLI exposes it as the review-url step output.

The direct link

The direct link is the preview URL with a #lyba_token=... fragment. Use it only as a fallback: it is convenient, but less durable than the short /r/<slug> link.

Review tokens

The token lives in the URL fragment, so it is not sent to your server as part of the request URL. The overlay sends it to Lyba as an X-Lyba-Token header, not as a server-visible query string.

If the toolbar says the review link is invalid or expired, the likely causes are an expired token, an ended session, or a Content Security Policy that blocked validation. Open the durable /r/<slug> review link again and check connect-src (see Content Security Policy). If previews sit behind SSO, the auth redirect drops the review token; disable protection for previews or use your host's bypass mechanism.

Opening a review link

The overlay appears only when three gates pass: your enabled prop is true (preview builds only), Lyba has not confidently detected production, and the URL carries a review token. Ordinary preview visitors see nothing. See Choosing the enabled gate.

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.

Comments and approvals

Comments

Comments belong to a session. Pins anchor to real DOM elements, not screenshots: Lyba stores a resilient selector plus the click offset inside the target element, and on reload the overlay re-resolves that selector to place the pin back on the live element. 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.

In the session's dashboard view your team sees every comment with its page, breakpoint and pin, plus the preview build (commit, branch, provider, PR), and can resolve, mark needs discussion, or reply to each one.

Approval

Request approval is enabled once every comment in the session is resolved; it 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. Approval receipts are created by Lyba's backend, not by the browser package.

The receipt is valid whether or not the client ever created an account. After a client approves, Lyba may email them an optional magic link to save their identity for future rounds; claiming only enriches attribution.

The next round

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

NextInstall the plugin →