# 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

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](https://docs.dev.board.fun/web/getting-started/build-and-deploy) for the packaging and deploy flow.