@flare/analytics-switch

A TypeScript React component library that provides a unified interface for integrating multiple analytics providers (Umami and Matomo) into React applications.

Features

• 🎯 Multi-provider support - Umami and Matomo analytics in one component
• 🔧 TypeScript - Full type safety and IntelliSense support
• 📦 Zero dependencies - Only peer dependencies on React
• ⚡ Performance - Conditional script loading based on configuration
• 🧪 Tested - Comprehensive test suite with Vitest
• 📱 Universal - Works in both browser and server-side rendering environments

Installation

# with npm
npm i --save @flare/analytics-switch --registry https://lab.code-rove.com/public-node-registry

# with yarn
yarn add @flare/analytics-switch --registry https://lab.code-rove.com/public-node-registry

# with pnpm
pnpm add @flare/analytics-switch --registry https://lab.code-rove.com/public-node-registry

Usage

Basic Usage

import React from "react";
import { AnalyticsSwitch } from "@flare/analytics-switch";

function App() {
  return (
    <div>
      <AnalyticsSwitch
        umami={{
          enabled: true,
          source: "https://your-umami-instance.com/script.js",
          websiteId: "your-website-id"
        }}
        matomo={{
          enabled: true,
          source: "https://your-matomo-instance.com/",
          websiteId: "1"
        }}
      />

      {/* Your app content */}
    </div>
  );
}

TypeScript Usage

The component provides full TypeScript support with proper type definitions:

import {
  AnalyticsSwitch,
  type AnalyticsSwitchProps
} from "@flare/analytics-switch";

const analyticsConfig: AnalyticsSwitchProps = {
  disabled: false, // Optional: disable all analytics
  umami: {
    enabled: process.env.NODE_ENV === "production",
    source: "https://analytics.yoursite.com/script.js",
    websiteId: "abc123"
  },
  matomo: {
    enabled: process.env.NODE_ENV === "production",
    source: "https://matomo.yoursite.com/",
    websiteId: "1"
  }
};

function App() {
  return <AnalyticsSwitch {...analyticsConfig} />;
}

Conditional Analytics

import { AnalyticsSwitch } from "@flare/analytics-switch";

function App() {
  const isProduction = process.env.NODE_ENV === "production";

  return (
    <AnalyticsSwitch
      disabled={!isProduction} // Disable all analytics in non-production
      umami={{
        enabled: true,
        source: "https://umami.example.com/script.js",
        websiteId: "website-id"
      }}
      // Matomo is optional - omit if not needed
    />
  );
}

API Reference

AnalyticsSwitchProps

Property	Type	Required	Description
disabled	boolean	No	Disable all analytics when true
umami	AnalyticsProvider	No	Umami analytics configuration
matomo	AnalyticsProvider	No	Matomo analytics configuration

AnalyticsProvider

Property	Type	Required	Description
enabled	boolean	Yes	Whether this analytics provider is enabled
source	string	Yes	Script source URL for the analytics provider
websiteId	string	Yes	Website/site ID for tracking

Development

Prerequisites

• Node.js 18+
• npm, yarn, or pnpm

Scripts

# Install dependencies
npm install

# Build the library
npm run build

# Run tests
npm run test

# Run tests with UI
npm run test:ui

# Run tests with coverage
npm run test:coverage

# Type checking
npm run typecheck

# Development mode with watch
npm run dev

# Lint and format
npm run lint
npm run lint:fix

Building

This library uses tsup for ultra-fast builds with esbuild:

• CommonJS: dist/index.js
• ES Modules: dist/index.mjs
• TypeScript declarations: dist/index.d.ts

Testing

Tests are written with Vitest and React Testing Library:

npm test              # Run tests
npm run test:ui       # Run with Vitest UI
npm run test:coverage # Run with coverage report

Publishing

# Patch version
npm run publish:patch

# Minor version
npm run publish:minor

# Major version
npm run publish:major

Changelog

See CHANGELOG.md for version history.

License

MIT - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request