{"id":13515336,"url":"https://github.com/derrickreimer/fathom-client","last_synced_at":"2025-04-04T06:06:45.206Z","repository":{"id":37887575,"uuid":"218443928","full_name":"derrickreimer/fathom-client","owner":"derrickreimer","description":"A Fathom Analytics library to help with client-side routing ","archived":false,"fork":false,"pushed_at":"2024-07-10T15:31:48.000Z","size":967,"stargazers_count":177,"open_issues_count":1,"forks_count":18,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-10-30T00:37:08.580Z","etag":null,"topics":["analytics","fathom-analytics"],"latest_commit_sha":null,"homepage":"http://npm.im/fathom-client","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/derrickreimer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-30T04:34:11.000Z","updated_at":"2024-10-17T06:25:09.000Z","dependencies_parsed_at":"2023-02-18T03:46:04.684Z","dependency_job_id":"13ab78a8-c015-4e4b-bb06-fdcc9dda9565","html_url":"https://github.com/derrickreimer/fathom-client","commit_stats":{"total_commits":92,"total_committers":12,"mean_commits":7.666666666666667,"dds":0.3913043478260869,"last_synced_commit":"a0279390d9e40e50a23766fe69b4b8f5c790a9fc"},"previous_names":["unstacked/fathom-client"],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derrickreimer%2Ffathom-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derrickreimer%2Ffathom-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derrickreimer%2Ffathom-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derrickreimer%2Ffathom-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/derrickreimer","download_url":"https://codeload.github.com/derrickreimer/fathom-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247128738,"owners_count":20888234,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","fathom-analytics"],"created_at":"2024-08-01T05:01:09.740Z","updated_at":"2025-04-04T06:06:45.184Z","avatar_url":"https://github.com/derrickreimer.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Fathom Client [![CircleCI](https://circleci.com/gh/derrickreimer/fathom-client.svg?style=svg)](https://circleci.com/gh/derrickreimer/fathom-client)\n\nThis library is a JavaScript client for [Fathom Analytics](https://usefathom.com/).\n\n- **Asynchronous script loading.** We provide a `load` function that will asynchronously inject the Fathom `\u003cscript\u003e` tag (great for single-page app environments).\n- **`import`-able tracking functions.** We provide tracking functions (`trackPageview` and `trackEvent`) that you can import and safely call anywhere (even if the Fathom script has not yet finished loading).\n\n---\n\nMaintained with ♥️ by the [SavvyCal](https://savvycal.com/?utm_source=github\u0026utm_medium=oss\u0026utm_campaign=fathom-client) team\n\n## Installation\n\nRun the following to install in your project:\n\n```\nnpm install fathom-client\n```\n\n## Motivation\n\nThe standard installation flow for Fathom is to drop their snippet on your page, which will automatically load the library and track a pageview. This approach works great for server-rendered sites with full page refreshes, but gets tricky when:\n\n- Routing happens on the client-side (e.g. an SPA)\n- The DOM is abstracted away (e.g. Next.js)\n\nThis library provides an interface you can use to orchestrate Fathom calls at various points in your page lifecycle:\n\n```js\nimport * as Fathom from 'fathom-client';\n\n// Upon initial page load...\nFathom.load('MY_FATHOM_ID');\n\n// In the route changed event handler...\nconst onRouteChangeComplete = () =\u003e {\n  Fathom.trackPageview();\n};\n\n// In an event handler where a goal is achieved...\nconst onSignUp = () =\u003e {\n  Fathom.trackEvent('Sign Up');\n};\n```\n\n## API Reference\n\n### `load(siteId: string, opts?: object)`\n\nInjects the Fathom script into the DOM and loads the script asynchronously.\n\n#### Arguments\n\n- `siteId` - The site ID provided in the Fathom UI.\n- `opts` - An Object of options:\n  - `auto` - When `false`, skips automatically tracking page views on script load (defaults to `true`).\n  - `honorDNT` - When `true`, honors the [DNT header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/DNT) in the visitor's browser\n  - `canonical` - When `false`, ignores the canonical tag if present (defaults to `true`).\n  - `spa` - Accepts one of the following values: `auto`, `history`, or `hash` (see [advanced docs](https://usefathom.com/support/tracking-advanced)).\n\n#### Example\n\n```js\nimport { load } from 'fathom-client';\n\nload('MY_FATHOM_ID', {\n  // Add options here\n});\n```\n\n### `trackPageview(opts?: object)`\n\nTracks a pageview.\n\n#### Arguments\n\n- `opts` - An Object of options:\n  - `url` - When set, overrides `window.location`.\n  - `referrer` - When set, overrides `document.referrer`.\n\n#### Example\n\n```js\nimport { trackPageview } from 'fathom-client';\n\ntrackPageview();\n```\n\n### `trackEvent(eventName: string, opts?: object)`\n\nTracks an event.\n\nSee [Creating and using events](https://usefathom.com/docs/features/events).\n\n#### Arguments\n\n- `eventName` - This can be nearly anything you want. Avoid special chars and emojis.\n- `opts` - An Object of options:\n  - `_site_id` - The Fathom site ID.\n  - `_value` - The value of the event (in cents).\n\n#### Example\n\n```js\nimport { trackEvent } from 'fathom-client';\n\ntrackEvent('checkout completed', { _value: 100 });\n```\n\n### `trackGoal(code: string, cents: number)`\n\nTracks a goal. **This is now deprecated, see `trackEvent` instead**.\n\n#### Arguments\n\n- `code` - the code provided in the Fathom UI.\n- `cents` - the value of the goal conversion.\n\n#### Example\n\n```js\nimport { trackGoal } from 'fathom-client';\n\ntrackGoal('MY_GOAL_CODE', 100);\n```\n\n### `enableTrackingForMe()`\n\nEnables tracking for the current visitor.\n\nSee https://usefathom.com/docs/features/exclude.\n\n#### Arguments\n\nNone.\n\n#### Example\n\n```js\nimport { enableTrackingForMe } from 'fathom-client';\n\nenableTrackingForMe();\n```\n\n### `blockTrackingForMe()`\n\nBlocks tracking for the current visitor.\n\nSee https://usefathom.com/docs/features/exclude.\n\n#### Arguments\n\nNone.\n\n#### Example\n\n```js\nimport { blockTrackingForMe } from 'fathom-client';\n\nblockTrackingForMe();\n```\n\n### `isTrackingEnabled()`\n\nChecks if tracking is enabled for the current visitor.\n\nSee https://usefathom.com/docs/features/exclude.\n\n#### Arguments\n\nNone.\n\n#### Returns\n\nBoolean.\n\n#### Example\n\n```js\nimport { isTrackingEnabled } from 'fathom-client';\n\nconst check = isTrackingEnabled(); // `true` by default\n```\n\n### `setSite(id: string)`\n\nSets the site ID for tracking (overrides the ID used when loading Fathom).\n\n#### Arguments\n\n- `id` - The site ID provided in the Fathom UI.\n\n#### Example\n\n```js\nimport { load, setSite } from 'fathom-client';\n\nload('MY_FATHOM_ID');\n\nsetSite('A_DIFFERENT_FATHOM_ID');\n```\n\n## Allowed Domains\n\nManage your allowed domains within your Fathom site's Firewall settings. Doing so enables the usage of wildcards (e.g., \\*.example.com). See https://usefathom.com/docs/script/firewall#allowed\n\nThe `includedDomains` and `excludedDomains` options, while deprecated, are still supported to ensure backward compatibility.\n\n## Usage\n\nThis library is JavaScript framework-agnostic. Below are some usage examples with popular frameworks.\n\n### Next.js\n\n#### Using `pages` directory (v12 and older)\n\n\u003e If you are using the latest Next.js beta with the `app` directory, see the modified instructions below.\n\nCreate an `_app.js` file in your `pages` directory, [like this](https://nextjs.org/docs#custom-app):\n\n```jsx\nimport React, { useEffect } from 'react';\nimport Router from 'next/router';\nimport * as Fathom from 'fathom-client';\n\n// Record a pageview when route changes\nRouter.events.on('routeChangeComplete', (as, routeProps) =\u003e {\n  if (!routeProps.shallow) {\n    Fathom.trackPageview();\n  }\n});\n\nfunction App({ Component, pageProps }) {\n  // Initialize Fathom when the app loads\n  useEffect(() =\u003e {\n    Fathom.load('MY_FATHOM_ID', {\n      // Add options here\n    });\n  }, []);\n\n  return \u003cComponent {...pageProps} /\u003e;\n}\n\nexport default App;\n```\n\n#### Using the experimental `app` directory (v13)\n\nCreate a `Fathom` client component:\n\n```tsx\n// Fathom.tsx\n'use client';\n\nimport { load, trackPageview } from 'fathom-client';\nimport { useEffect, Suspense } from 'react';\nimport { usePathname, useSearchParams } from 'next/navigation';\n\nfunction TrackPageView() {\n  const pathname = usePathname();\n  const searchParams = useSearchParams();\n\n  // Load the Fathom script on mount\n  useEffect(() =\u003e {\n    load('MY_FATHOM_ID', {\n      auto: false\n    });\n  }, []);\n\n  // Record a pageview when route changes\n  useEffect(() =\u003e {\n    if (!pathname) return;\n\n    trackPageview({\n      url: pathname + searchParams?.toString(),\n      referrer: document.referrer\n    });\n  }, [pathname, searchParams]);\n\n  return null;\n}\n\nexport default function Fathom() {\n  return (\n    \u003cSuspense fallback={null}\u003e\n      \u003cTrackPageView /\u003e\n    \u003c/Suspense\u003e\n  );\n}\n```\n\nNote that we explicitly pass the `url` to `trackPageview` to avoid race conditions that occur when we allow the Fathom script to infer the URL from the browser.\n\nThen, add the client component to your root `layout.tsx` file:\n\n```tsx\n// layout.tsx\n\nimport Fathom from './Fathom';\n\nexport default function RootLayout({ children }: { children: ReactNode }) {\n  return (\n    \u003chtml lang=\"en\"\u003e\n      \u003chead\u003e\u003c/head\u003e\n      \u003cbody\u003e\n        \u003cFathom /\u003e\n        {children}\n      \u003c/body\u003e\n    \u003c/html\u003e\n  );\n}\n```\n\n## Upgrading to 3.x\n\nThe 3.0 release comes with a new way to load Fathom:\n\n```diff\n- Fathom.load();\n- Fathom.setSiteId('MY_FATHOM_ID');\n+ Fathom.load('MY_FATHOM_ID');\n```\n\nThe `load` function also accepts an object of options:\n\n```js\nFathom.load('MY_FATHOM_ID', {\n  // Add options here\n});\n```\n\nSee [advanced options for tracking](https://usefathom.com/support/tracking-advanced).\n\n## Releasing\n\nRun the following to publish a new version:\n\n```bash\nnpm run release\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fderrickreimer%2Ffathom-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fderrickreimer%2Ffathom-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fderrickreimer%2Ffathom-client/lists"}