vite-plugin-fathom

0.1.0 verified Mon Apr 27 auth: no javascript

A Vite plugin that injects the Fathom analytics script into HTML pages during build. Current stable version is 0.1.0. It is a lightweight, single-purpose plugin with peer dependency on Vite >= 6.0.0. It supports environment variable-based configuration via VITE_FATHOM_ID and advanced Fathom options like forceEU, spa, honorDNT, autoTrack, and ignoreCanonical. Differentiators: minimal setup, TypeScript type definitions included, and automatic script injection without manual template modification.

Common errors

error Error: The Fathom site ID must be provided via the VITE_FATHOM_ID environment variable or as the first argument. ↓

cause No site ID provided and env var not set.

fix

Set VITE_FATHOM_ID=YOUR_SITE_ID or call vitePluginFathom('YOUR_SITE_ID').

error TypeError: vitePluginFathom is not a function ↓

cause Importing as named export instead of default import.

fix

Use import vitePluginFathom from 'vite-plugin-fathom' instead of destructured import.

error Error: Vite 6 is required for this plugin ↓

cause Vite version below 6.0.0.

fix

Upgrade Vite to version 6 or later using npm install vite@^6.

Warnings

breaking Requires Vite version >= 6.0.0. Older Vite versions will fail to load the plugin. ↓

fix Upgrade Vite to 6.0.0 or later: npm install vite@^6.0.0

gotcha Environment variable VITE_FATHOM_ID must be set (or pass site ID explicitly) otherwise the plugin will throw. ↓

fix Set VITE_FATHOM_ID in .env file or pass site ID as first argument.

gotcha Options object is optional; if omitted, defaults to empty object. ↓

fix Ensure if you need custom options, pass them as second argument.

Install

npm install vite-plugin-fathom

yarn add vite-plugin-fathom

pnpm add vite-plugin-fathom

Imports

default (vitePluginFathom)

wrong

import { vitePluginFathom } from 'vite-plugin-fathom'

correct

import vitePluginFathom from 'vite-plugin-fathom'

This package exports a default function, not a named export.

type FathomOptions

wrong

import { FathomOptions } from 'vite-plugin-fathom'

correct

import type { FathomOptions } from 'vite-plugin-fathom'

FathomOptions is a TypeScript type, use import type to avoid runtime issues.

plugin call
wrong
```
new vitePluginFathom()
```
correct
```
vitePluginFathom()
```
The default export is a function, not a constructor.

Quickstart

Minimal Vite config integrating the Fathom plugin with environment variable and options.

// vite.config.ts
import { defineConfig } from 'vite';
import vitePluginFathom from 'vite-plugin-fathom';

export default defineConfig({
  plugins: [
    vitePluginFathom(process.env.VITE_FATHOM_ID ?? '', {
      forceEU: true,
      spa: 'auto',
      honorDNT: true,
    }),
  ],
});