analytics-switch/README.md

# @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

```bash
# 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

```tsx
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:

```tsx
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

```tsx
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

```bash
# 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](https://tsup.egoist.dev/) 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](https://vitest.dev/) and [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/):

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

## Publishing

```bash
# Patch version
npm run publish:patch

# Minor version
npm run publish:minor

# Major version
npm run publish:major
```

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for version history.

## License

MIT - see [LICENSE](./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