# @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 (
{/* Your app content */}
); } ``` ### 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 ; } ``` ### Conditional Analytics ```tsx import { AnalyticsSwitch } from "@flare/analytics-switch"; function App() { const isProduction = process.env.NODE_ENV === "production"; return ( ); } ``` ## 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