Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createClient
✓ import { createClient } from 'passji/client'
✗ import { createClient } from 'passji'
Browser/client-side SDK is in the /client subpath.
createServer
✓ import { createServer } from 'passji/server'
✗ import { createServer } from 'passji'
Server-side SDK is in the /server subpath. Use this for code exchange and token verification.
PassjiProvider
✓ import { PassjiProvider, usePassji } from 'passji/react'
✗ import { PassjiProvider } from 'passji'
React components are exported from 'passji/react'.
Passji (NextAuth)
✓ import Passji from 'passji/nextauth'
✗ import { Passji } from 'passji/nextauth'
NextAuth provider is a default export from 'passji/nextauth'.
passji (Better Auth)
✓ import { passji } from 'passji/better-auth'
✗ import passji from 'passji/better-auth'
Better Auth helper is a named export 'passji' from 'passji/better-auth'.
Demonstrates client-side authorization URL generation with PKCE, server-side code exchange and ID token verification, and React hooks integration.
import { createClient } from 'passji/client';
import { createServer } from 'passji/server';
import { PassjiProvider, usePassji } from 'passji/react';
// Client-side: generate authorization URL with PKCE
const client = createClient({
clientId: process.env.PASSJI_CLIENT_ID ?? '',
redirectUri: 'http://localhost:3000/callback'
});
const { url, codeVerifier } = await client.createAuthorizationURL();
// Server-side: exchange code for tokens
const server = createServer({
clientId: process.env.PASSJI_CLIENT_ID ?? '',
clientSecret: process.env.PASSJI_CLIENT_SECRET ?? '',
redirectUri: 'http://localhost:3000/callback'
});
const tokens = await server.exchangeCode('code', codeVerifier);
const user = await server.verifyIdToken(tokens.idToken);
console.log(user.emojiId);
// React: use PassjiProvider and usePassji
function App() {
return (
<PassjiProvider clientId={process.env.PASSJI_CLIENT_ID ?? ''} onToken={(token) => fetch('/api/auth', { method: 'POST', body: JSON.stringify({ token }) })}>
<LoginButton />
</PassjiProvider>
);
}
function LoginButton() {
const { signIn, user } = usePassji();
if (user) return <span>{user.emojiId}</span>;
return <button onClick={signIn}>Sign in</button>;
}
Errors
Common errors & fixes
Cannot find module 'passji/client'
Import from 'passji/client' but the package is not installed or version is old.
fixInstall passji: npm install passji@latest
Passji is not defined (NextAuth)
Importing Passji as default but using named import.
fixUse: import Passji from 'passji/nextauth' (default import)
Uncaught TypeError: Cannot destructure property 'signIn' of '(0 , ...).usePassji(...)' as it is undefined.
usePassji hook used outside of PassjiProvider.
fixWrap your component tree with <PassjiProvider> before using usePassji.
TypeError: client.createAuthorizationURL is not a function
Imported createClient from 'passji' instead of 'passji/client'.
fixChange import to: import { createClient } from 'passji/client' Audit
Dependencies
expressoptionalFor Express server integration (server SDK)
express-sessionoptionalRequired for Express session support
honooptionalFor Hono framework integration
nextoptionalFor Next.js integration (nextauth export)
reactoptionalFor React client-side hooks and components
secretdefoptionalUsed for secret definition/schema