@geenius/analytics

Privacy-first analytics primitives, UI components, and backend provider helpers for Geenius applications across shared runtime, React, React CSS, SolidJS, SolidJS CSS, Convex, Neon, Cloudflare KV, and Memory entrypoints.

Install

pnpm add @geenius/analytics

Install the framework peers you use in your application:

pnpm add react react-dom
pnpm add solid-js
pnpm add convex
pnpm add @neondatabase/serverless drizzle-orm

Current Run Scope

The current package gauntlet is driven by variants.json and the Omega scope file. These UI variants are active: react, react-css, solidjs, solidjs-css, and react-native. The DB providers convex, neon, cloudflareKV, and memory are active.

Deferred UI-library adapters remain declared in the canonical manifest with inScope: false and are excluded from local build, type-check, Storybook, Playwright, size, and coverage sweeps until the run scope changes.

The deferred adapters are react-ant, react-chakra, react-daisyui, react-heroui, react-mantine, react-mui, react-shadcn, solidjs-ark, solidjs-kobalte, and solidjs-solidui.

Public Imports

Shared utilities from the root export:

import {
  createTracker,
  defaultAnalyticsConfig,
  analyzeFunnel,
} from '@geenius/analytics'

Shared validators and privacy helpers are also exported from the root. Do not import a shared subpath; implementation packages stay private. UI providers/components/hooks are exported from UI variant subpaths, DB stores from DB provider subpaths, and Convex functions from @geenius/analytics/convex. Use cloudflareKV for provider ids and public imports; lowercase driver labels such as cloudflare-kv are implementation metadata.

import {
  AnalyticsEventSchema,
  sanitizeAnalyticsEvent,
} from '@geenius/analytics'

React hooks, providers, and Tailwind-based UI:

import {
  AnalyticsProvider,
  StatsCard,
  useAnalytics,
} from '@geenius/analytics/react'

React vanilla-CSS components:

import '@geenius/analytics/react-css/styles.css'
import {
  AnalyticsProvider,
  StatsCard,
} from '@geenius/analytics/react-css'

The react-css entrypoint ships a standalone stylesheet for host-app theming.

SolidJS primitives, providers, and Tailwind-based UI:

import {
  AnalyticsProvider,
  StatsCard,
  createAnalytics,
} from '@geenius/analytics/solidjs'

SolidJS vanilla-CSS components:

import '@geenius/analytics/solidjs-css/styles.css'
import {
  AnalyticsProvider,
  StatsCard,
} from '@geenius/analytics/solidjs-css'

The solidjs-css entrypoint ships a standalone stylesheet for host-app theming.

Convex schema, queries, and mutations:

import {
  analyticsSchema,
  trackEvent,
  getRealtimeStats,
} from '@geenius/analytics/convex'

Neon, Cloudflare KV, and Memory stores:

import { createCloudflareKVAnalyticsStore } from '@geenius/analytics/cloudflareKV'
import { createMemoryAnalyticsStore } from '@geenius/analytics/memory'
import { createNeonAnalyticsStore } from '@geenius/analytics/neon'

React Native components and primitives:

import {
  AnalyticsProvider,
  MetricCard,
  useAnalytics,
} from '@geenius/analytics/react-native'

Basic Usage

import {
  AnalyticsProvider,
  StatsCard,
  useAnalytics,
} from '@geenius/analytics/react'
import { defaultAnalyticsConfig } from '@geenius/analytics'

function OverviewCard() {
  const analytics = useAnalytics()

  async function handleOpen(): Promise<void> {
    await analytics.track('dashboard_opened', {
      surface: 'overview',
    })
  }

  return (
    <button onClick={() => void handleOpen()}>
      <StatsCard
        label="Unique visitors"
        value="12,480"
        change="+6.4%"
        trend="up"
      />
    </button>
  )
}

export function AnalyticsExample() {
  return (
    <AnalyticsProvider
      config={{
        ...defaultAnalyticsConfig,
        trackPageViews: true,
        debug: false,
      }}
    >
      <OverviewCard />
    </AnalyticsProvider>
  )
}

Storybook Review Apps

This package includes V2 Storybook v10 review apps for the active UI variants in variants.json. Deferred Storybook shells may remain on disk, but the package build and test scripts filter them out by default.

pnpm storybook:react
pnpm storybook:react-css
pnpm storybook:solidjs
pnpm storybook:solidjs-css

Production verification uses:

pnpm storybook:react:build
pnpm test:storybook:build
pnpm test:storybook

Contributing tests

The test matrix is driven by variants.json. Re-include a deferred launch variant there first, then update the matching package under packages/, public export in package.json, harness registration, and Storybook app. Do not add one-off variant arrays to scripts or Playwright config.

Every package subdirectory must keep the TypeScript config trio: tsconfig.json, tsconfig.typecheck.json, and tsconfig.build.json. The convention suites under __tests__/conventions/ enforce workspace deps, tsconfig shape, public surface, Storybook V2 app shape, and ecosystem consumption.

Common gates:

pnpm lint
pnpm type-check
pnpm test:unit
pnpm test:packed-smoke
pnpm test:coverage
pnpm test:coverage:diff
pnpm size
pnpm audit:supply-chain
pnpm test:gauntlet
pnpm test:all

Visual regression is default-on in Playwright. For fast local loops only, set PW_VISUAL=0; update committed baselines with pnpm test:visual --update-snapshots.

License

Functional Source License 1.1 with Apache-2.0 future license. See LICENSE.