# use-fathom-client

> This is an unofficial client implementation for Fathom analytics.

Latest version **1.3.3** (published 2023-07-07) · GPL-3.0-or-later license · 0 weekly downloads

## Install

```sh
npm install use-fathom-client
pnpm add use-fathom-client
yarn add use-fathom-client
bun add use-fathom-client
```

Provides the command `prepare-fathom`.

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.3 |
| Published | 2023-07-07 |
| First published | 2023-05-11 |
| Weekly downloads | 0 |
| License | GPL-3.0-or-later |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=14.16 |
| Dependencies | 4 |
| Unpacked size | 56.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | pg.guerrap@proton.me |
| Maintainers | guerrap |
| Keywords | use-fathom, analytics, fathom, client |

## Links

- npm: https://www.npmjs.com/package/use-fathom-client
- Repository: https://github.com/guerrap/use-fathom-client
- Homepage: https://github.com/guerrap/use-fathom-client#readme
- Issues: https://github.com/guerrap/use-fathom-client/issues
- npm.io page: https://npm.io/package/use-fathom-client

## Dependencies (4)

- [ora](https://npm.io/package/ora.md) ^6.3.0
- [dotenv](https://npm.io/package/dotenv.md) ^16.0.3
- [find-up](https://npm.io/package/find-up.md) ^6.3.0
- [node-fetch](https://npm.io/package/node-fetch.md) ^3.3.1

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 1.3.3 (latest) — 2023-07-07
- 1.3.2 — 2023-06-08
- 1.3.1 — 2023-05-15
- 1.3.0 — 2023-05-15
- 1.2.0 — 2023-05-12
- 1.1.0 — 2023-05-11
- 1.0.0 — 2023-05-11

## README

# Use Fathom Client

## Introduction

The Fathom Client package is designed to make it easier for developers to integrate [`Fathom Analytics`](https://usefathom.com) on a Single Page Application (SPA), where routing is done client-side.

## Features

With this package, developers can take advantage of the following key features:

- An `initialize` function to asyncronously inject the Fathom `script`
- A series of wrappers around the Fathom functions that can be called even if the Fathom script has not yet loaded
- A `prepare-fathom` script that can automatically generate Fathom events dynamically

## Installation

To install the package, run:

```sh
npm install use-fathom-client
```

## Basic usage

Once installed, Fathom can initialized with the `FATOM_SITE_ID` (obtained by registering on Fathom) and with a configuration object that must include the Fathom's script location (it should be a CDN endpoint, more details [here](https://usefathom.com/docs/script/embed)). The `initialize` function supports a third optional parameter that enhances the usage when dealing with events registerd on Fathom (more on this later).

```ts
import * as Fathom from "use-fathom-client";

Fathom.initialize("FATHOM_SITE_ID", {
  src: "FATHOM_SCRIPT",
  "data-auto": false,
  "data-spa": "auto",
});
```

After initializing, you can use the exported functions throughout your application:

```ts
import * as Fathom from "use-fathom-client";

// Track a page view
Fathom.trackPageview();
// Track a pre-registered goal
Fathom.trackGoal();
```

## Usage with event sync

### Event sync

As mentioned earlier, the library includes a `prepare-fathom` script that can automatically create event entities on the target Fathom site (using Fathom's API), given a list of event names. Since the script interacts with the Fathom API, you need to define a couple of environment variables:

- `FATHOM_SITE_ID`: the site id
- `FATHOM_API_KEY`: the API key secret

The script uses `dotenv` to read environment variables, so you'll need to create a `.env` file in the root directory of your project:

```sh
FATHOM_SITE_ID=""
FATHOM_API_KEY=""
```

If the required environment variables are not defined, the script will still function; however, it will skip the events synchronization process. Instead, it will only generate the output files to prevent any disruption to builds that depend on the generated output.

Additionally, the script requires a configuration file named either `.fathomrc`, or`.fathomrc.json` as a starting point for the event definitions. This file should be in `JSON` format, placed in the root of your project, and should contain the desired event names.

```json
{
  "events": ["CUSTOM_EVENT_NAME", "ANOTHER_CUSTOM_EVENT_NAME"]
}
```

With the `outDir` property

```json
{
  "outDir": "out/fathom",
  "events": ["CUSTOM_EVENT_NAME", "ANOTHER_CUSTOM_EVENT_NAME"]
}
```

Once defined the script can be run by adding a dedicated entry to your `package.json`, like this:

```json
{
  "scripts": {
    "setup-fathom": "prepare-fathom"
  }
}
```

The `prepare-fathom` script is designed to ensure that the events defined in the `.fathomrc` file are synchronized with those on the remote Fathom site. If any events are missing on the remote site, the script will create them automatically. On the other hand, if there are events that exist on the remote site but are not defined in the local mapping, the script will add them to the `.fathomrc` file. Once you run the `prepare-fathom` script, the `.fathomrc` file should be fully aligned with the remote site.

### Code generation

Once the events have been synchronized, the `prepare-fathom` script proceeds to generate three files under the default `out/fathom` directory (if a custom directory is not specified in the configuration file). These files will be located within the `src` directory:

- `mappings.ts`: this file contains an array that includes all the registered events.
- `types.ts`: type definitions about the registered events.
- `utilities.ts`: it exports a `registeredEventsResolver` function that can be used to retrieve a registered event id by its name.

### Use the generated code

After all events have been synchronized and the code has been generated, Fathom can be initialized with the `registeredEventsResolver`, which enables the `trackRegisteredGoal` function.

```ts
import * as Fathom from "use-fathom-client";
import { registeredEventsResolver } from "./out/fathom/utilities";

Fathom.initialize(
  "FATHOM_SITE_ID",
  {
    src: "FATHOM_SCRIPT",
    "data-auto": false,
    "data-spa": "auto",
  },
  registeredEventsResolver
);
```

To import the `registeredEventsResolver`, simply reference the generated `utilities` file.

After initializing Fathom with this resolver (as shown in the example above), all exported functions can be used without issue, with the exception of `trackRegisteredGoal`. To use this function, you must first specify which events it should support.

```ts
import * as Fathom from "use-fathom-client";
import { FathomRegisteredEventName } from "./out/fathom/types";

// Track a registered goal
Fathom.trackRegisteredGoal<FathomRegisteredEventName>("", 0);
```

To import the `FathomRegisteredEventName` mapping, simply reference the generated `types` file.

With this mapping imported, you can now use the `Fathom.trackRegisteredGoal<T>` type, which supports all events defined in the configuration file.

## Delete an event

Keep in mind that if you need to delete an event, you should first remove it from the Fathom dashboard, then delete it from your local configuration file and finally run `prepare-fathom`; if the event exists either locally or remotely, it will be syncronized.

---
_Source: https://npm.io/package/use-fathom-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._