Installation
Registry access, peer dependencies, and verifying it worked.
Before you start
Two things have to be in place, and only one of them is on your side.
From us: a community provisioned on the FanBase platform, and the environment values for it. Your contact at FanBase sends these. They are listed in Environment.
From you: a GitHub Personal Access Token with the read:packages scope on the @xborglabs organisation. The packages are published to GitHub Packages, not the public npm registry, so a plain npm install cannot see them until this is configured.
Requirements
| React | 19 |
| react-dom | matching your React version |
@tanstack/react-query | ^5 |
| Package manager | npm, pnpm, yarn or bun |
React 19 is a hard requirement. The React bindings use the use() hook, which does not exist in React 18, and an app on 18 fails at module load rather than at runtime.
@tanstack/react-query is a peer dependency and you own the QueryClient. The SDK does not install its own.
Point npm at GitHub Packages
Add to .npmrc in your project root:
@xborglabs:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}Then export the token in your shell or CI environment:
export GITHUB_TOKEN=ghp_your_token_hereKeep the token out of the file itself. The ${GITHUB_TOKEN} reference above is expanded by npm at install time.
Install
Ask for the alpha tag by name:
npm install @xborglabs/fanbase-core@alpha @xborglabs/fanbase-react@alphaBoth packages are released together and the tag moves to the current release of each, so this resolves them as a matching pair.
Which tag
Three tags exist, and they do not carry the same features.
| Tag | Has every feature in these docs |
|---|---|
alpha | Yes |
beta | Yes |
latest | Yes. It is the stable one, and trails the other two by a few weeks. |
A bare npm install, with no tag, installs latest.
All three carry every feature in these docs. What differs is which FanBase environment they are built against and how recently they changed. Name the tag, so an install next month gets what you tested today. Ask your FanBase contact which one your community is provisioned against.
If npm install fails with ETARGET, your token is fine. It means the tag you
asked for does not exist, usually a typo in it.
Verify
node -e "console.log(require('@xborglabs/fanbase-react/package.json').version)"If that prints a version, the registry and token are working. If it fails to resolve, the .npmrc scope line is the usual cause.
Typecheck note for Vite apps
The stock Vite React template ships a root tsconfig.json that only contains project references. Running tsc --noEmit against it checks nothing and exits 0, which reads as a clean typecheck when it is not one.
Point at the app config instead:
npx tsc -p tsconfig.app.json --noEmitWorth putting in your package.json scripts so nobody has to remember it.
Next
Environment, then Quickstart.