@glydi/passkey-react

Thin React/Next.js adapter for the Glide passkey Web Component.

Install

Glide is not yet published to npm. Install from a packed tarball or via pnpm link.

Tarball (recommended):

{
  "dependencies": {
    "@glydi/passkey-react": "file:../glide/dist-packs/glydi-passkey-react-0.1.0.tgz",
    "@glydi/passkey-core":  "file:../glide/dist-packs/glydi-passkey-core-0.1.0.tgz"
  },
  "pnpm": {
    "overrides": {
      "@glydi/passkey-core": "file:../glide/dist-packs/glydi-passkey-core-0.1.0.tgz"
    }
  }
}

The pnpm.overrides entry for @glydi/passkey-core prevents pnpm from trying to fetch the transitive peer from the npm registry. See docs/DISTRIBUTION.md for full tarball and pnpm link instructions, including how to produce the tarballs.

Forthcoming: npm install @glydi/passkey-react will be the public form once the package is published. It is not yet available on npm.

Minimal Usage

Declarative <PasskeyButton>

PasskeyButton declares "use client" — it is a Client Component and must not be imported from server-only code.

// Source: apps/example/app/page.tsx
"use client";
import { PasskeyButton } from "@glydi/passkey-react";

<PasskeyButton
  mode="signup"
  label="Register passkey"
  onSuccess={(result) => console.log("registered", result.user.id)}
  onError={(e) => console.warn(e.code, e.message)}
/>

Headless usePasskeyAuth

For custom UI, use the headless hook — it returns a ref to attach to a <biometric-auth-button> element alongside reactive state:

// Source: packages/react/src/usePasskeyAuth.ts
"use client";
import { usePasskeyAuth } from "@glydi/passkey-react";
import "@glydi/passkey-core/define";

export default function MyPage() {
  const { ref, phase, isPending, error, user } = usePasskeyAuth({
    mode: "auto",
    onSuccess: (r) => router.push("/app"),
  });
  return (
    <biometric-auth-button ref={ref} label={isPending ? "…" : "Sign in"} />
  );
}

API

PasskeyButton

A React wrapper around <biometric-auth-button>. Declares "use client" — import only in Client Components or pages marked "use client".

PasskeyButtonProps:

| Prop | Type | Default | Description | |------|------|---------|-------------| | mode | "auto" \| "signin" \| "signup" | "auto" | Auth mode. See AuthMode callout below. | | username | string | — | Username hint for registration/conditional UI. | | label | string | — | Button label text. | | endpoints | Partial<GlideEndpoints> | — | Override one or more API endpoint paths. | | fetchOptions | RequestInit | — | Merged into every fetch call (e.g. custom headers). | | onSuccess | (result: AuthResult) => void | — | Called after successful authentication. | | onError | (error: GlideError) => void | — | Called when authentication fails. | | prime | boolean | — | Show a pre-prompt explainer before the OS biometric sheet. | | primeTitle | string | — | Title for the priming panel. | | primeBody | string | — | Body text for the priming panel. | | primeContinue | string | — | Continue button label in the priming panel. | | primeCancel | string | — | Cancel button label in the priming panel. | | fallbackHref | string | — | URL of a recovery page (e.g. magic-link). Shown on unsupported/error. | | fallbackLabel | string | — | Label for the fallback link. | | className | string | — | CSS class forwarded to the host element. | | style | React.CSSProperties | — | Inline style forwarded to the host element. |

Valid mode values are "auto", "signin", and "signup" only. Using "register" or "authenticate" is invalid and will silently no-op.

usePasskeyAuth(options?)

Headless hook. Returns a UsePasskeyAuth object:

| Return value | Type | Description | |---|---|---| | ref | RefObject<GlideElement \| null> | Attach to <biometric-auth-button ref={ref}>. | | phase | AuthPhase | Current auth phase ("idle", "loading", "success", etc.). | | isPending | boolean | true during "loading" or "authenticating". | | isUnsupported | boolean | true when phase === "unsupported". | | error | GlideError \| null | Last error, or null. | | user | GlideUser \| null | Authenticated user after success, or null. | | trigger() | () => void | Imperatively start auth (same as clicking the button). | | reset() | () => void | Reset phase and error back to "idle". |

UsePasskeyAuthOptions (all optional):

| Option | Type | Description | |--------|------|-------------| | mode | "auto" \| "signin" \| "signup" | Auth mode. Default "auto". | | username | string | Username hint. | | endpoints | Partial<GlideEndpoints> | Override API endpoint paths. | | fetchOptions | RequestInit | Merged into every fetch call. | | onSuccess | (result: AuthResult) => void | Success callback. | | onError | (error: GlideError) => void | Error callback. |

Re-exported types

AuthMode, AuthPhase, AuthResult, GlideEndpoints, GlideError, GlideUser

Links

• Root README — architecture overview
• Quickstart — full Next.js App Router integration walkthrough
• Distribution guide — tarball and pnpm link install details