trackly-react 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,121 @@
1
+ # @analytics/react
2
+
3
+ React integration for [@analytics/sdk](../sdk).
4
+
5
+ ## 🚀 Instalação
6
+
7
+ ```bash
8
+ pnpm add @analytics/sdk @analytics/react react
9
+ ```
10
+
11
+ ## 📦 Uso
12
+
13
+ ### 1. Wrap your app com AnalyticsProvider
14
+
15
+ ```tsx
16
+ // app/layout.tsx
17
+ import { AnalyticsProvider } from "@analytics/react";
18
+
19
+ export default function RootLayout({ children }) {
20
+ return (
21
+ <html>
22
+ <body>
23
+ <AnalyticsProvider
24
+ config={{
25
+ apiUrl: process.env.NEXT_PUBLIC_ANALYTICS_API_URL,
26
+ debug: process.env.NODE_ENV === "development",
27
+ }}
28
+ >
29
+ {children}
30
+ </AnalyticsProvider>
31
+ </body>
32
+ </html>
33
+ );
34
+ }
35
+ ```
36
+
37
+ ### 2. Use o hook `useAnalytics`
38
+
39
+ ```tsx
40
+ import { useAnalytics } from "@analytics/react";
41
+
42
+ function MyComponent() {
43
+ const analytics = useAnalytics();
44
+
45
+ const handlePurchase = () => {
46
+ analytics.track("purchase_completed", {
47
+ amount: 99.9,
48
+ currency: "BRL",
49
+ items: 2,
50
+ });
51
+ };
52
+
53
+ return <button onClick={handlePurchase}>Buy Now</button>;
54
+ }
55
+ ```
56
+
57
+ ### 3. Use componentes de tracking
58
+
59
+ ```tsx
60
+ import { TrackClick, TrackView } from '@analytics/react';
61
+
62
+ // Track clicks
63
+ <TrackClick eventName="signup_clicked" properties={{ source: 'header' }}>
64
+ <button>Sign Up</button>
65
+ </TrackClick>
66
+
67
+ // Track views (on mount)
68
+ <TrackView eventName="modal_opened" properties={{ type: 'promo' }}>
69
+ <Modal>Promo content</Modal>
70
+ </TrackView>
71
+ ```
72
+
73
+ ### 4. Use hooks utilitários
74
+
75
+ ```tsx
76
+ import { usePageview, useTrackEvent, useIdentify } from "@analytics/react";
77
+
78
+ function ProductPage({ productId }) {
79
+ // Auto-track pageview on mount
80
+ usePageview({ category: "product", productId });
81
+
82
+ // Track evento com dependências
83
+ useTrackEvent("product_viewed", { productId }, [productId]);
84
+
85
+ return <div>Product {productId}</div>;
86
+ }
87
+
88
+ function App({ user }) {
89
+ // Identify user quando mudar
90
+ useIdentify(user?.id, { email: user?.email, plan: user?.plan }, [user]);
91
+
92
+ return <div>App</div>;
93
+ }
94
+ ```
95
+
96
+ ## 🎯 API
97
+
98
+ ### Components
99
+
100
+ - **`<AnalyticsProvider>`** - Context provider (obrigatório no root)
101
+ - **`<TrackClick>`** - Wrapper para tracking de clicks
102
+ - **`<TrackView>`** - Wrapper para tracking de views (mount)
103
+
104
+ ### Hooks
105
+
106
+ - **`useAnalytics()`** - Retorna instância do Analytics
107
+ - **`usePageview(properties?)`** - Auto-track pageview no mount
108
+ - **`useTrackEvent(name, properties?, deps?)`** - Track evento com deps reativas
109
+ - **`useIdentify(userId?, traits?, deps?)`** - Identify user com deps reativas
110
+
111
+ ## 🔧 TypeScript
112
+
113
+ Totalmente tipado. Import types do SDK:
114
+
115
+ ```tsx
116
+ import type { EventProperties, UserTraits } from "@analytics/react";
117
+ ```
118
+
119
+ ## 📝 Licença
120
+
121
+ MIT
@@ -0,0 +1,34 @@
1
+ import { type ReactNode } from "react";
2
+ import { Analytics, type AnalyticsConfig } from "@analytics/sdk";
3
+ export interface AnalyticsProviderProps {
4
+ config: AnalyticsConfig;
5
+ children: ReactNode;
6
+ }
7
+ /**
8
+ * Provider para Analytics SDK
9
+ *
10
+ * @example
11
+ * ```tsx
12
+ * <AnalyticsProvider config={{ apiUrl: 'https://api.example.com/events' }}>
13
+ * <App />
14
+ * </AnalyticsProvider>
15
+ * ```
16
+ */
17
+ export declare function AnalyticsProvider({ config, children, }: AnalyticsProviderProps): import("react/jsx-runtime").JSX.Element;
18
+ /**
19
+ * Hook para acessar instância do Analytics
20
+ *
21
+ * @example
22
+ * ```tsx
23
+ * function MyComponent() {
24
+ * const analytics = useAnalytics();
25
+ *
26
+ * const handleClick = () => {
27
+ * analytics.track('button_clicked', { label: 'signup' });
28
+ * };
29
+ *
30
+ * return <button onClick={handleClick}>Sign Up</button>;
31
+ * }
32
+ * ```
33
+ */
34
+ export declare function useAnalytics(): Analytics;
@@ -0,0 +1,49 @@
1
+ "use client";
2
+ import { jsx as _jsx } from "react/jsx-runtime";
3
+ import { createContext, useContext, useEffect, useMemo, } from "react";
4
+ import { Analytics } from "@analytics/sdk";
5
+ const AnalyticsContext = createContext(null);
6
+ /**
7
+ * Provider para Analytics SDK
8
+ *
9
+ * @example
10
+ * ```tsx
11
+ * <AnalyticsProvider config={{ apiUrl: 'https://api.example.com/events' }}>
12
+ * <App />
13
+ * </AnalyticsProvider>
14
+ * ```
15
+ */
16
+ export function AnalyticsProvider({ config, children, }) {
17
+ const analytics = useMemo(() => new Analytics(config), [config.apiUrl]);
18
+ useEffect(() => {
19
+ // Cleanup: flush eventos pendentes ao desmontar
20
+ return () => {
21
+ analytics.flush();
22
+ };
23
+ }, [analytics]);
24
+ return (_jsx(AnalyticsContext.Provider, { value: analytics, children: children }));
25
+ }
26
+ /**
27
+ * Hook para acessar instância do Analytics
28
+ *
29
+ * @example
30
+ * ```tsx
31
+ * function MyComponent() {
32
+ * const analytics = useAnalytics();
33
+ *
34
+ * const handleClick = () => {
35
+ * analytics.track('button_clicked', { label: 'signup' });
36
+ * };
37
+ *
38
+ * return <button onClick={handleClick}>Sign Up</button>;
39
+ * }
40
+ * ```
41
+ */
42
+ export function useAnalytics() {
43
+ const analytics = useContext(AnalyticsContext);
44
+ if (!analytics) {
45
+ throw new Error("useAnalytics must be used within AnalyticsProvider. " +
46
+ "Wrap your app with <AnalyticsProvider>.");
47
+ }
48
+ return analytics;
49
+ }
@@ -0,0 +1,34 @@
1
+ import { type ReactElement } from 'react';
2
+ import type { EventProperties } from '@analytics/sdk';
3
+ export interface TrackClickProps {
4
+ eventName: string;
5
+ properties?: EventProperties;
6
+ children: ReactElement;
7
+ }
8
+ /**
9
+ * Wrapper para tracking de clicks
10
+ *
11
+ * @example
12
+ * ```tsx
13
+ * <TrackClick eventName="cta_clicked" properties={{ location: 'hero' }}>
14
+ * <button>Sign Up</button>
15
+ * </TrackClick>
16
+ * ```
17
+ */
18
+ export declare function TrackClick({ eventName, properties, children }: TrackClickProps): ReactElement<any, string | import("react").JSXElementConstructor<any>>;
19
+ export interface TrackViewProps {
20
+ eventName: string;
21
+ properties?: EventProperties;
22
+ children: ReactElement;
23
+ }
24
+ /**
25
+ * Wrapper para tracking de visualizações (mount)
26
+ *
27
+ * @example
28
+ * ```tsx
29
+ * <TrackView eventName="modal_viewed" properties={{ type: 'signup' }}>
30
+ * <Modal>Content</Modal>
31
+ * </TrackView>
32
+ * ```
33
+ */
34
+ export declare function TrackView({ eventName, properties, children }: TrackViewProps): ReactElement<any, string | import("react").JSXElementConstructor<any>>;
@@ -0,0 +1,41 @@
1
+ 'use client';
2
+ import { cloneElement, useEffect } from 'react';
3
+ import { useAnalytics } from './AnalyticsProvider';
4
+ /**
5
+ * Wrapper para tracking de clicks
6
+ *
7
+ * @example
8
+ * ```tsx
9
+ * <TrackClick eventName="cta_clicked" properties={{ location: 'hero' }}>
10
+ * <button>Sign Up</button>
11
+ * </TrackClick>
12
+ * ```
13
+ */
14
+ export function TrackClick({ eventName, properties, children }) {
15
+ const analytics = useAnalytics();
16
+ const handleClick = (e) => {
17
+ analytics.track(eventName, properties);
18
+ // Preserva onClick original se existir
19
+ if (children.props.onClick) {
20
+ children.props.onClick(e);
21
+ }
22
+ };
23
+ return cloneElement(children, { onClick: handleClick });
24
+ }
25
+ /**
26
+ * Wrapper para tracking de visualizações (mount)
27
+ *
28
+ * @example
29
+ * ```tsx
30
+ * <TrackView eventName="modal_viewed" properties={{ type: 'signup' }}>
31
+ * <Modal>Content</Modal>
32
+ * </TrackView>
33
+ * ```
34
+ */
35
+ export function TrackView({ eventName, properties, children }) {
36
+ const analytics = useAnalytics();
37
+ useEffect(() => {
38
+ analytics.track(eventName, properties);
39
+ }, [analytics, eventName, properties]);
40
+ return children;
41
+ }
@@ -0,0 +1,37 @@
1
+ import type { EventProperties } from "@analytics/sdk";
2
+ /**
3
+ * Hook para tracking automático de pageviews
4
+ *
5
+ * @example
6
+ * ```tsx
7
+ * function PageLayout() {
8
+ * usePageview(); // Trackeia ao montar
9
+ * return <div>Content</div>;
10
+ * }
11
+ * ```
12
+ */
13
+ export declare function usePageview(properties?: EventProperties): void;
14
+ /**
15
+ * Hook para tracking com deps reativas
16
+ *
17
+ * @example
18
+ * ```tsx
19
+ * function Product({ id }) {
20
+ * useTrackEvent('product_viewed', { productId: id }, [id]);
21
+ * return <div>Product {id}</div>;
22
+ * }
23
+ * ```
24
+ */
25
+ export declare function useTrackEvent(eventName: string, properties?: EventProperties, deps?: any[]): void;
26
+ /**
27
+ * Hook para identificar usuário quando deps mudarem
28
+ *
29
+ * @example
30
+ * ```tsx
31
+ * function App({ user }) {
32
+ * useIdentify(user?.id, { email: user?.email }, [user]);
33
+ * return <div>App</div>;
34
+ * }
35
+ * ```
36
+ */
37
+ export declare function useIdentify(userId: string | undefined, traits?: Record<string, any>, deps?: any[]): void;
package/dist/hooks.js ADDED
@@ -0,0 +1,58 @@
1
+ "use client";
2
+ import { useEffect } from "react";
3
+ import { useAnalytics } from "./AnalyticsProvider";
4
+ /**
5
+ * Hook para tracking automático de pageviews
6
+ *
7
+ * @example
8
+ * ```tsx
9
+ * function PageLayout() {
10
+ * usePageview(); // Trackeia ao montar
11
+ * return <div>Content</div>;
12
+ * }
13
+ * ```
14
+ */
15
+ export function usePageview(properties) {
16
+ const analytics = useAnalytics();
17
+ useEffect(() => {
18
+ analytics.pageview(properties);
19
+ }, [analytics, properties]);
20
+ }
21
+ /**
22
+ * Hook para tracking com deps reativas
23
+ *
24
+ * @example
25
+ * ```tsx
26
+ * function Product({ id }) {
27
+ * useTrackEvent('product_viewed', { productId: id }, [id]);
28
+ * return <div>Product {id}</div>;
29
+ * }
30
+ * ```
31
+ */
32
+ export function useTrackEvent(eventName, properties, deps = []) {
33
+ const analytics = useAnalytics();
34
+ useEffect(() => {
35
+ analytics.track(eventName, properties);
36
+ // eslint-disable-next-line react-hooks/exhaustive-deps
37
+ }, [analytics, eventName, ...deps]);
38
+ }
39
+ /**
40
+ * Hook para identificar usuário quando deps mudarem
41
+ *
42
+ * @example
43
+ * ```tsx
44
+ * function App({ user }) {
45
+ * useIdentify(user?.id, { email: user?.email }, [user]);
46
+ * return <div>App</div>;
47
+ * }
48
+ * ```
49
+ */
50
+ export function useIdentify(userId, traits, deps = []) {
51
+ const analytics = useAnalytics();
52
+ useEffect(() => {
53
+ if (userId) {
54
+ analytics.identify(userId, traits);
55
+ }
56
+ // eslint-disable-next-line react-hooks/exhaustive-deps
57
+ }, [analytics, userId, ...deps]);
58
+ }
@@ -0,0 +1,30 @@
1
+ /**
2
+ * @analytics/react - React integration for Analytics SDK
3
+ *
4
+ * @example
5
+ * ```tsx
6
+ * import { AnalyticsProvider, useAnalytics, TrackClick } from '@analytics/react';
7
+ *
8
+ * function App() {
9
+ * return (
10
+ * <AnalyticsProvider config={{ apiUrl: 'https://api.example.com/events' }}>
11
+ * <MyApp />
12
+ * </AnalyticsProvider>
13
+ * );
14
+ * }
15
+ *
16
+ * function MyApp() {
17
+ * const analytics = useAnalytics();
18
+ *
19
+ * return (
20
+ * <TrackClick eventName="signup_clicked" properties={{ source: 'homepage' }}>
21
+ * <button>Sign Up</button>
22
+ * </TrackClick>
23
+ * );
24
+ * }
25
+ * ```
26
+ */
27
+ export { AnalyticsProvider, useAnalytics } from "./AnalyticsProvider";
28
+ export { usePageview, useTrackEvent, useIdentify } from "./hooks";
29
+ export { TrackClick, TrackView } from "./components";
30
+ export type { AnalyticsConfig, EventProperties, UserTraits, EventContext, } from "@analytics/sdk";
package/dist/index.js ADDED
@@ -0,0 +1,29 @@
1
+ /**
2
+ * @analytics/react - React integration for Analytics SDK
3
+ *
4
+ * @example
5
+ * ```tsx
6
+ * import { AnalyticsProvider, useAnalytics, TrackClick } from '@analytics/react';
7
+ *
8
+ * function App() {
9
+ * return (
10
+ * <AnalyticsProvider config={{ apiUrl: 'https://api.example.com/events' }}>
11
+ * <MyApp />
12
+ * </AnalyticsProvider>
13
+ * );
14
+ * }
15
+ *
16
+ * function MyApp() {
17
+ * const analytics = useAnalytics();
18
+ *
19
+ * return (
20
+ * <TrackClick eventName="signup_clicked" properties={{ source: 'homepage' }}>
21
+ * <button>Sign Up</button>
22
+ * </TrackClick>
23
+ * );
24
+ * }
25
+ * ```
26
+ */
27
+ export { AnalyticsProvider, useAnalytics } from "./AnalyticsProvider";
28
+ export { usePageview, useTrackEvent, useIdentify } from "./hooks";
29
+ export { TrackClick, TrackView } from "./components";
package/package.json ADDED
@@ -0,0 +1,48 @@
1
+ {
2
+ "name": "trackly-react",
3
+ "version": "0.1.0",
4
+ "description": "React integration for trackly-sdk",
5
+ "main": "dist/index.js",
6
+ "module": "dist/index.js",
7
+ "types": "dist/index.d.ts",
8
+ "files": [
9
+ "dist"
10
+ ],
11
+ "scripts": {
12
+ "build": "tsc",
13
+ "dev": "tsc --watch",
14
+ "clean": "rm -rf dist"
15
+ },
16
+ "keywords": [
17
+ "analytics",
18
+ "react",
19
+ "hooks",
20
+ "tracking",
21
+ "react-hooks",
22
+ "event-tracking",
23
+ "typescript"
24
+ ],
25
+ "author": "",
26
+ "license": "MIT",
27
+ "repository": {
28
+ "type": "git",
29
+ "url": "git+https://github.com/kaycfarias/trackly.git",
30
+ "directory": "packages/react"
31
+ },
32
+ "bugs": {
33
+ "url": "https://github.com/kaycfarias/trackly/issues"
34
+ },
35
+ "homepage": "https://github.com/kaycfarias/trackly/tree/main/packages/react#readme",
36
+ "peerDependencies": {
37
+ "react": ">=18.0.0",
38
+ "trackly-sdk": "workspace:*"
39
+ },
40
+ "devDependencies": {
41
+ "@types/react": "^18.2.48",
42
+ "react": "^18.2.0",
43
+ "typescript": "^5.9.3"
44
+ },
45
+ "dependencies": {
46
+ "trackly-sdk": "workspace:*"
47
+ }
48
+ }