Quickstart
Sign-in and a live quest list, running locally.
Assumes installation is done and you have your environment values.
Doing this with a coding agent instead? Agent setup has the prompts. This page is the same path by hand.
1. Wrap your app
FanbaseProvider holds configuration, the session, and the API client. It goes above anything that touches FanBase.
import { FanbaseProvider } from '@xborglabs/fanbase-react'
import { QueryClient } from '@tanstack/react-query'
const queryClient = new QueryClient()
const session = {
get: () => JSON.parse(localStorage.getItem('fanbase.session') ?? 'null'),
set: (s) => localStorage.setItem('fanbase.session', JSON.stringify(s)),
clear: () => localStorage.removeItem('fanbase.session'),
}
export function App() {
return (
<FanbaseProvider
tenant={import.meta.env.VITE_FANBASE_TENANT}
slug={import.meta.env.VITE_FANBASE_COMMUNITY_SLUG}
appId={import.meta.env.VITE_FANBASE_APP_ID}
httpOptions={{
gamerBaseUrl: import.meta.env.VITE_FANBASE_GAMER_BASE_URL,
locale: import.meta.env.VITE_FANBASE_LOCALE ?? 'en',
}}
session={session}
queryClient={queryClient}
>
<Routes />
</FanbaseProvider>
)
}Two things worth knowing before you go further.
The session adapter is any object with get, set and clear. localStorage is fine to start. Swap in cookies or your own store later without touching anything else.
FanbaseProvider mounts its own QueryClientProvider around your children, using the client you passed. Your own useQuery calls need to sit inside it, which they will if FanbaseProvider is near the root.
2. Sign in
Two helpers build the URL, then you navigate to it.
import { buildOAuthProxyUrl, buildLoginUrl } from '@xborglabs/fanbase-react'
const proxyUrl = buildOAuthProxyUrl({
oauthProxyUrl: import.meta.env.VITE_FANBASE_OAUTH_PROXY_URL,
proxySecret: import.meta.env.VITE_FANBASE_OAUTH_PROXY_SECRET,
})
function signIn(provider) {
sessionStorage.setItem('fanbase.provider', provider)
const redirectUrl = new URL(import.meta.env.VITE_FANBASE_OAUTH_REDIRECT_URL)
redirectUrl.searchParams.set('provider', provider)
window.location.href = buildLoginUrl({
oauthProxyUrl: proxyUrl,
provider,
redirectUrl: redirectUrl.toString(),
})
}provider is one of google, discord, twitter, twitch. It is the identity provider and nothing else. Passing a tenant or a community slug here is the most common first mistake.
The proxy returns to your callback with ?token= and nothing else, so stash the provider before you leave. Both the query param and sessionStorage above do that, either alone is enough.
3. Handle the callback
This page has to live at exactly the URL registered as your redirect.
import { useEffect } from 'react'
import { useFanbase, parseOAuthCallbackToken } from '@xborglabs/fanbase-react'
export function AuthCallback() {
const { state, actions } = useFanbase()
useEffect(() => {
if (!state.ready) return
const token = parseOAuthCallbackToken(window.location.href)
if (!token) return
const provider =
new URLSearchParams(window.location.search).get('provider') ??
sessionStorage.getItem('fanbase.provider')
actions.loginWithToken({ provider, token })
}, [state.ready])
return <p>Signing you in…</p>
}Wait for state.ready. The provider restores any existing session on mount, and exchanging a token before that finishes puts you in an inconsistent state.
The provider you pass to loginWithToken has to match the one you passed to buildLoginUrl. A mismatch fails the exchange.
You are signed in when state.session has both accessToken and refreshToken. From there the SDK sends the access token as a Bearer header on every request. No cookies involved.
actions.logout() clears the adapter and the in-memory session.
4. List quests
import { useQuestsList } from '@xborglabs/fanbase-react'
export function QuestList() {
const { data: quests, isLoading } = useQuestsList()
if (isLoading) return <Spinner />
return (
<ul className="your-grid">
{quests.map((quest) => (
<li key={quest.id}>
<YourCard quest={quest} onOpen={() => open(quest)} />
</li>
))}
</ul>
)
}One call, one request. Do not fetch per-quest detail or reward allocations for cards. Everything a card needs is on the row you already have, and fanning out turns one request into dozens.
Quests appear here as soon as someone publishes them in the admin panel. No deploy.
Two things on rendering: quest status comes back as a raw enum like INACTIVE, which does not mean what it looks like, and quest descriptions are structured content rather than plain strings. Display strings and Quest descriptions cover both. They are quick reads and skipping them is the usual cause of a first build looking rough.
5. Quest detail and claim
That is the substantial part, and it has its own pages: Quest detail and Rewards and claims.
Check it worked
- Quest list renders and matches your admin panel
- Sign-in returns to your callback and
state.sessionhas both tokens actions.logout()clears it- Refresh keeps you signed in
- Network tab shows one
GET /v1/questson the list page, not one per card