<!-- Canonical source: https://github.com/deancochran/ftms/blob/2586e33ac88d5d945d9658e063bb909cd58462bd/examples/typescript-quickstart/README.md; revision: 2586e33ac88d5d945d9658e063bb909cd58462bd -->

# TypeScript quickstart

Prerequisites: Node.js 20+ and npm. The package is ESM-only; `.mjs` works without
changing an application's module setting. TypeScript declarations ship with it.

## Add to your application

```sh
npm install @deancochran/ftms
```

This selects npm's `latest` dist-tag. Retain the saved dependency and lockfile,
and consult the changelog when upgrading. See [all-port installation guidance](https://deancochran.github.io/ftms/start/installation/index.md).

## Reproduce the verified example

From this directory in a source checkout (the example deliberately pins its tested release):

```sh
npm install --ignore-scripts --no-audit --no-fund
npm start
npm test
```

Alternatively, copy `package.json`, `main.mjs`, `recipes.mjs` and `transport.mjs`
to a new directory and run the same commands. All imports resolve through the
installed npm package, not repository source. This example pins the current
[verified release](https://deancochran.github.io/ftms/project/releases/index.md); the older
[0.2.0 client](https://github.com/deancochran/ftms/blob/main/examples/typescript-client/README.md) is a separate compatibility fixture.

Expected `npm start` output (after npm's command banner):

```text
speedMps=10 cadenceRpm=90 powerWatts=250 hrBpm=null
complete.truncated=false short.truncated=true
```

`main.mjs` asserts every displayed value. `npm test` additionally exercises UUID
dispatch, features, ranges, control codecs, a nonzero-offset DataView, and
nullable base64 from the react-native-ble-plx payload contract. `base64-js` is an
example-only conversion dependency; it is not a dependency of the protocol core.

Read [main.mjs](https://github.com/deancochran/ftms/blob/main/examples/typescript-quickstart/main.mjs), then [recipes.mjs](https://github.com/deancochran/ftms/blob/main/examples/typescript-quickstart/recipes.mjs) and
[transport.mjs](https://github.com/deancochran/ftms/blob/main/examples/typescript-quickstart/transport.mjs). The [cookbook](https://deancochran.github.io/ftms/integration/cookbook/index.md) explains
API choices and application responsibilities.

These tests are host-only and send no commands. They do not validate browser
permissions, Metro, a mobile BLE stack, device behavior, or physical control safety.
