Getting Started
Installation
Add the package to a Better Auth app.
Install @onmax/better-auth-cross-device in the app that owns your Better Auth server. The server plugin and browser helpers ship from separate entrypoints so each side imports only what it needs.
Quick Start
1. Install the package
pnpm add @onmax/better-auth-cross-device
bun add @onmax/better-auth-cross-device
npm install @onmax/better-auth-cross-device
yarn add @onmax/better-auth-cross-device
2. Check Better Auth
The plugin expects Better Auth >=1.4.18 <2. Install or update Better Auth in the same app:
Terminal
pnpm add better-auth
3. Import the server plugin
Use the package root in your Better Auth configuration:
auth.ts
import { crossDevice, CrossDeviceProofError } from "@onmax/better-auth-cross-device"
4. Import the client plugin
Use the /client entrypoint in browser code:
auth-client.ts
import { crossDeviceClient } from "@onmax/better-auth-cross-device/client"
The client helpers call the Better Auth endpoints exposed by the server plugin. Register both sides before building the approval UI.
Defaults
| Option | Default |
|---|---|
endpointPrefix | /cross-device |
orderTtlSeconds | 120 |
tokenHeaderName | set-auth-token |
orderModelName | crossDeviceOrder |
enforceOrigin | true |
claimPathTemplate | /cross-device/claim/{orderId}?token={claimToken} |
Next Steps
- Server setup: register the plugin and proof adapter
- Client setup: start, subscribe, approve, and finalize orders
- Endpoint reference: review the HTTP contract