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.

A minimal project

The npm create @board.fun/game scaffold generates a Vite project, but the SDK is bundler-agnostic, so any ESM toolchain works. To wire it into a fresh project by hand:

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

No special bundler config is required for the SDK itself; standard 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.

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