Setup Reference

Configuration notes for using the Board Web SDK in a real project. The Quick Start gets you running in five minutes; this is the deeper reference for tsconfig, bundlers, runtime detection, and integration with web frameworks.

Module format

@board.fun/web-sdk ships as ESM only with full TypeScript types. There is no CommonJS or UMD build, and no global script-tag distribution. Any modern bundler (Vite, esbuild, webpack 5, Rollup, Parcel) works.

  • "type": "module" is set in the package.
  • Exports: ./dist/index.js (runtime), ./dist/index.d.ts (types).
  • moduleResolution: "bundler" (or "node16"/"nodenext") in your tsconfig.

If you’re targeting an older toolchain that only understands CommonJS, you’ll need a bundler step.

The Web SDK is built and tested against Vite. A minimal Vite project for Board:

npm create vite@latest my-board-game -- --template vanilla-ts
cd my-board-game
npm install @board.fun/web-sdk

No special vite.config.ts is required for the SDK itself; standard Vite defaults work.

Runtime detection

Always guard SDK calls with Board.isOnDevice so your code can run in a browser tab (for development) and on a Board device without branching everywhere:

import { Board } from "@board.fun/web-sdk";

if (Board.isOnDevice) {
  Board.input.subscribe(handleContacts);
}

On a regular browser tab Board.isOnDevice is false. Off-device, device-backed calls throw (sync) or reject (async) because the native bridge is absent, so guard them with Board.isOnDevice. The one exception is Board.input.getContacts(), which reads a local snapshot and returns []. With the guard in place you can still hot-reload and iterate on UI without a device.

Versioning

Board.sdkVersion reports the package’s semver string for informational purposes. It is not a feature gate. The bridge between the SDK and the OS handles capability discovery internally; new platform features degrade gracefully on older OS versions. For runtime readiness checks (services like the player profile registry coming online), use Board.session.areServicesReady().

TypeScript types

All public types are exported from the package root:

import {
  Board,
  BoardContactType,
  BoardContactPhase,
  type BoardContact,
  type BoardPlayer,
  type BoardSaveGameMetadata,
} from "@board.fun/web-sdk";

Use the type-only imports (type ...) for shapes you only reference in annotations.

Where the app runs

A Web SDK app runs inside Board’s built-in browser (“Board Browser”), a system-managed WebView. You don’t ship an APK; you ship a built web app and Board Connect installs and launches it on the device. See Build & Deploy for the packaging and deploy flow.

See Also