@coinlist-co/react package is the recommended way to integrate Passage in React and Next.js apps with a backend. It gives you OAuth with PKCE on the client, token exchange and sessions on the server, and ready-made UI for common flows.
For a linear walkthrough, start with SDK quickstart.
Requirements
- React 18+ and React DOM 18+, and viem ^2 (peer dependencies)
- A backend you control to store
client_secret, exchange authorization codes, and keep refresh tokens out of the browser
Install
Entry points
The package exposes three canonical entry points:
Most apps import everything they need from
@coinlist-co/react. Reach for /server only inside server-side code, and /universal when you want a domain type without pulling the client bundle. Sub-path imports like @coinlist-co/react/client/components and /client/hooks were removed in v0.5.0, and /shared was renamed to /universal in v0.12.0 - see the React SDK changelog.
Namespaces
The whole public surface is namespaces. On the client,init() is the only top-level member, because it is lifecycle rather than domain; CoinListServer has none at all.
CoinList’s own namespaces are named after what they do. A third-party provider’s namespace is named after the provider, because a second provider ships its own swap and coinlist.swap could only ever mean one of them.
Methods follow one vocabulary, with the namespace’s own noun dropped:
list() (every item, auto-paginating), listPage(params), get(id), and create* / submit* / remove* for writes, plus a real domain verb where one exists (connectExternal, allowWallet, execute). Any method taking more than one argument takes a single params object. SDK structure explains why the namespaces are named as they are, and the patterns the hooks and components above follow.
Unless a namespace says otherwise, its API-backed methods require a logged-in user and throw NotAuthenticatedError. coinlist.tokens is the exception: it is public, so it works with no session and with a read-only server session store.
v0.11.0 moved the last flat methods into namespaces and renamed coinlist.swap to coinlist.superstate. v0.12.0 forked coinlist.ondo’s order builders by direction. See the changelog for the full migration tables.
Next steps
SDK structure
The ladder, namespaces, hook state, and flows that return instead of throwing.
Set up OAuth authentication
End-to-end sign-in with backend session.
Building the Checkout flow
One container that renders whichever provider an offer belongs to.
Errors and edge cases
Every error shape the flows return, and how to handle them.