How it works

How it fits together

The layer model, the state machine, and the unstyled contract.

The model, before any code. Fifteen minutes here saves a lot of guessing later.

Three layers

The FanBase platform. Our API and admin panel. Holds your community, your quests, your fans and their progress. Your community team works here.

@xborglabs/fanbase-core. A framework-free client. Talks to the platform, holds the quest state machine, the template registry, reward resolution and the display string catalog. No React, no DOM.

@xborglabs/fanbase-react. React bindings on top of core. A provider, hooks, and slot-based components that render your markup rather than theirs.

Your app sits above all three and owns every pixel.

Why the split

Core is where the rules live. Whether a fan can submit a quest right now, what the button should say, which reward image to show. Those rules are identical whatever framework you use, so they sit in a package with no framework in it.

That is also why a Vue or Svelte binding is possible later without rewriting the logic. Only React exists today.

The state machine

The single most useful thing to understand.

Whether a quest can be acted on depends on a pile of conditions: is the fan signed in, have they linked the right social account, have they already completed it, is it inside its date window, did they open the link. Getting that wrong means fans hitting buttons that fail.

You do not evaluate any of it. Core runs a state machine over the quest and everything you have told it about the fan, and gives you back a decision:

FieldWhat it is
state.canSubmitWhether the fan can act right now
state.canClaimWhether there is a reward waiting
state.buttonLabelThe right label for the current state
state.disabledReasonLabelWhy the fan cannot act, in readable language

Change the fan's condition and watch what the machine reports:

Fan condition

What the fan sees

Follow @FanBase on Discord

Join the server, say hello, and claim what it pays out.

Not StartedresolveMessage('Quests.status.INACTIVE')

You need to log in to start this quest.

What the machine reports

state.canSubmit
false
state.canClaim
false
state.buttonLabel
"Sign in to start"
state.disabledReasonLabel
"You need to log in to start this quest."

You render these four fields. You never compute them. That is what keeps your app working when a new quest type ships.

Simulated locally so the docs build without registry access. Behaviour matches the SDK.

Render those four fields. Do not reimplement the logic, and do not bypass the machine with your own enabled check. When new quest types ship, apps that trusted the machine keep working.

The machine is only as good as what you feed it. If you do not pass the fan's linked socials, it has to assume nothing is linked, and quests that need a linked account stay disabled. Quest detail covers what to pass.

Unstyled by design

The components use a slot pattern. You pass your own element, the component attaches behaviour to it.

<Quest.Submit asChild>
  <button className="your-button">Complete</button>
</Quest.Submit>

Your class names come through untouched. Nothing is added. There is no FanBase stylesheet in your bundle and no iframe.

The one place we do give you content is descriptions, which are structured rather than plain text, and there you pass a theme object mapping node types to your classes. See Quest descriptions.

Requests

Every request carries two things: the xb-tenant header, which scopes data to your community, and once signed in, a Bearer access token. No cookies, so no third-party cookie problem and no CORS credential dance.

The SDK is built around few requests. The quest list is one call for the whole list. Detail is one call per quest, when a fan opens it. If you find yourself fetching per card, something is wired wrong.

Where content comes from

Quests are created and edited in the FanBase admin panel by whoever runs your community. They appear in your app through the API, so a new quest is a publish, not a deploy.

This shapes how you build. You are not writing a component per quest. You write one detail view that handles every quest type, driven by the quest's template. Quest templates is the map of what can arrive.

On this page