@synqauth/react

React hooks and components for Synq.

Synq is customer identity for businesses: an OpenID Connect issuer for each of your brands, with Solana wallet, social, email and passkey sign-in. The documentation is at docs.synq.build.

This package is at 0.x, so a minor release can change its API: see its CHANGELOG.md.

Quick start

@synqauth/react talks to your app's own route mount, which @synqauth/nextjs serves, so the browser never holds a Synq token. Set that up first (its README), then give the pages that need the session a provider, in a route group's layout so the rest of the app (marketing pages, say) stays static:

// app/(app)/layout.tsx
import { SynqProvider } from '@synqauth/react'
import { synq } from '@/lib/synq'

export default async function AppLayout({ children }: { children: React.ReactNode }) {
  return <SynqProvider initialSession={await synq.getSession()}>{children}</SynqProvider>
}

// app/(app)/settings/page.tsx
import '@synqauth/react/styles.css'
import { AccountManager, UserButton, WalletManager } from '@synqauth/react'

export default function Settings() {
  return (
    <>
      <UserButton accountHref="/settings" />
      <AccountManager />
      <WalletManager />
    </>
  )
}

To sign people in on your own page (own-UI sign-in, on for the app in the dashboard), render <SignInForm returnTo="/dashboard" />, lay out its parts (PasskeyButton, PasswordForm, EmailCodeForm, VerifyEmailForm) your own way, or build your own form on useSignIn(). It offers a passkey where the browser can use the brand's on your page (Chrome and Edge 128+, Safari 18+, Firefox 152+), then an emailed code or a password. Anything only Synq's hosted page can do, such as a token gate, goes there.

The hooks are useSession(), useSignIn(), useUser(), useWallets(), useLinkedAccounts(), useAccountSessions() and useAuth(). Every call answers { data, error } and never throws, and a change clicked twice while it's under way is sent once.

The components take Synq's look from @synqauth/react/styles.css: Molly's design for Synq, dark with teal actions and pill buttons, and a light counterpart when the page prefers light. Theme it with CSS variables (--synq-color-primary, --synq-color-surface, --synq-radius...; a button that is off takes --synq-color-disabled, --synq-color-disabled-border and --synq-color-disabled-text), or take none of it with unstyled. <AccountManager> shows the profile, the ways to sign in, passkeys, devices and deleting the account (sections picks and orders them); it offers to add the ways your brand turns on, as the account API lists them (useLinkableMethods()), and linkMethods narrows them. "Add a passkey" shows only where the brand offers passkeys, and makes one on Synq's add-passkey page; elsewhere passkeys are listed and removed, never added. Removing a way in, a wallet or the account asks first. <SynqProvider messages> puts their words in your app's language.

Plugins hold functions, which a server component can't pass: an app with plugins wraps SynqProvider in a client component of its own.

License

MIT