@threenine/nuxt-fathom

@threenine/nuxt-fathom

Nuxt module to integrate Fathom Analytics.

This is a fork of the original Nuxt Fathom, and all credit should go to the original developers, However this release include upgrade to the Nuxt 4, improved unit test and added support for Nuxt 4 Composables.

To use this plugin you will need a Fathom Analytics account which you can sign up with using Fathom Analytics Free trial

To learn more about Fathom Analytics checkout the following link:

• Why Choose privacy focused Analytics

We fixed some bugs with how the script is injected and loaded, and updated in general to make the plugin work out the box with NUxt 4 based websites.

Features

• ⚡ Automatic or manual tracking
• 📯 Automatically imported composables
• 🏷️ Fully typed Fathom API
• 🦾 SSR-ready
• 📂 Environment Variable support

Installation

Running the following command will:

• Install the module as a dependency using your package manager.
• Add it to your package.json file.
• Update your nuxt.config file.

## with npm
npx nuxi module add @threenine/nuxt-fathom

Basic Usage

Provide your Fathom site ID in your nuxt.config file.

// `nuxt.config.ts`
export default defineNuxtConfig({
  modules: ["@threenine/nuxt-fathom"],

  fathom: {
    siteId: "FATHOM_SITE_ID",
  },
});

Tip: you can also use an Environment Variables instead of a fathom key.

Done! Fathom Analytics will now run in your application's client.

Configuration

All supported module options can be configured using the fathom key in your Nuxt configuration:

export default defineNuxtConfig({
  modules: ['@threenine/nuxt-fathom'],

  fathom: {
    // The Fathom Analytics site ID to use for tracking
    siteId: string,
    // Additional configuration
    config: {
      manual?: boolean
      auto?: boolean
      honorDNT?: boolean
      canonical?: boolean
      spa?: 'auto' | 'history' | 'hash'
    }
  }
})

Runtime Config

Instead of hard-coding your Fathom Analytics site ID in your Nuxt configuration, you can set your desired option in your project's .env file, leveraging automatically replaced public runtime config values by matching environment variables at runtime.

# Overwrites the `fathom.siteId` module option
NUXT_PUBLIC_FATHOM_SITE_ID=YOUR_SITE_ID

With this setup, you can omit the fathom key in your Nuxt configuration if you only intend to set the site ID.

Module Options

Property	Type	Description	Default
manual	boolean	If you want to manually control page view tracking.	false
auto	boolean	When false, skips automatically tracking page views on script load.	true
honorDNT	boolean	When true, honors the DNT header in the visitor's browser.	false
canonical	boolean	When false, ignores the canonical tag if present.	true
spa	'auto', 'history', 'hash'	Accepts one of the following values: auto, history, or hash (see advanced docs).	undefined

Composables

As with other composables in the Nuxt 4 ecosystem, they are auto-imported and can be used in your application's components.

useFathom

The SSR-safe useFathom composable provides access to:

• The blockTrackingForMe method.
• The enableTrackingForMe method.
• The isTrackingEnabled method.
• The setSite method.
• The trackEvent method.
• The trackPageview method.

It can be used as follows:

// Each method is destructurable from the composable
const {
  blockTrackingForMe,
  enableTrackingForMe,
  isTrackingEnabled,
  setSite,
  trackEvent, // The method most likely to be used.
  trackPageview,
} = useFathom();

[!NOTE] Since the fathom instance is available in the client only, any useFathom method calls executed on the server will have no effect.

Development

# Install dependencies
pnpm install

# Generate type stubs
pnpm run dev:prepare

# Develop with the playground
pnpm run dev

# Build the playground
pnpm run dev:build

# Run ESLint
pnpm run lint

# Run Vitest
pnpm run test
pnpm run test:watch

# Release new version
pnpm run release

CI Test

To test the GitHub Actions locally, you can use act.

# Install act
brew install nektos/tap/act

## Run act CI workflow
act -W .github/workflows/ci.yml

Credits

• johannschopplich for his nuxt-gtag project.
• derrickreimer for his fathom-client.
• valgeirb for his original nuxt-fathom project which this is a fork of .

Support

⚡️ lightning address:

[e-mail]