{"_id":"@achado/react","_rev":"2-a7ad83ac3368bed203299f8633d244ee","name":"@achado/react","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.1":{"name":"@achado/react","version":"0.0.1","keywords":["react","analytics","tracking","achado","hooks","components"],"author":{"name":"Achado"},"license":"MIT","_id":"@achado/react@0.0.1","maintainers":[{"name":"achado","email":"achadolabs@gmail.com"}],"homepage":"https://github.com/achado/js-monorepo","bugs":{"url":"https://github.com/achado/js-monorepo/issues"},"dist":{"shasum":"0c3924386fe99d50f5a2f2592658b750476a38ac","tarball":"https://registry.npmjs.org/@achado/react/-/react-0.0.1.tgz","fileCount":65,"integrity":"sha512-VTFRcKEjZWmWnMv5QskqIsmYJLsw/YsHayEn15MPlzjukePvap6MqotCYyoGEjG1dNibJB7bi75/HVK4/6OJhg==","signatures":[{"sig":"MEQCIGpBv8hMBxeH2TZfWlLyXd8Q9mSpYi8eFAW0lvcb2SM5AiBtziXEQoq94PZ5ZHodbF9P3RZq6vKok05w983O1iCxRg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":592858},"main":"dist/index.js","type":"commonjs","_from":"file:achado-react-0.0.1.tgz","types":"dist/types/index.d.ts","module":"dist/index.esm.js","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"},"./package.json":"./package.json"},"scripts":{"dev":"rollup -c -w","lint":"eslint src --ext .ts,.tsx","test":"vitest","build":"rollup -c","clean":"rm -rf dist","test:watch":"vitest --watch","type-check":"tsc --noEmit"},"_npmUser":{"name":"achado","email":"achadolabs@gmail.com"},"_resolved":"/tmp/51233bf9951cedc252aeb31b3245170e/achado-react-0.0.1.tgz","_integrity":"sha512-VTFRcKEjZWmWnMv5QskqIsmYJLsw/YsHayEn15MPlzjukePvap6MqotCYyoGEjG1dNibJB7bi75/HVK4/6OJhg==","repository":{"url":"git+https://github.com/achado/js-monorepo.git","type":"git","directory":"packages/react"},"_npmVersion":"10.9.3","description":"React bindings for Achado analytics SDK","directories":{},"sideEffects":false,"_nodeVersion":"22.20.0","dependencies":{"@achado/client":"0.0.1"},"_hasShrinkwrap":false,"devDependencies":{"react":"^18.2.0","@types/react":"^18.2.0"},"peerDependencies":{"react":"^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"},"_npmOperationalInternal":{"tmp":"tmp/react_0.0.1_1759924668821_0.6721946331095383","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@achado/react","version":"0.0.2","type":"commonjs","description":"React bindings for Achado analytics SDK","main":"dist/index.js","module":"dist/index.esm.js","types":"dist/types/index.d.ts","exports":{".":{"import":"./dist/esm/index.js","require":"./dist/cjs/index.js","types":"./dist/types/index.d.ts"},"./package.json":"./package.json"},"sideEffects":false,"dependencies":{"@achado/client":"0.0.2"},"peerDependencies":{"react":"^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"},"devDependencies":{"@types/react":"^18.2.0","react":"^18.2.0"},"keywords":["react","analytics","tracking","achado","hooks","components"],"author":{"name":"Achado"},"license":"MIT","homepage":"https://github.com/achado/js-monorepo","repository":{"type":"git","url":"git+https://github.com/achado/js-monorepo.git","directory":"packages/react"},"scripts":{"build":"rollup -c","dev":"rollup -c -w","clean":"rm -rf dist","test":"vitest","test:watch":"vitest --watch","lint":"eslint src --ext .ts,.tsx","type-check":"tsc --noEmit"},"_id":"@achado/react@0.0.2","bugs":{"url":"https://github.com/achado/js-monorepo/issues"},"_integrity":"sha512-OKmOjebM3VPpjZYDDB7TmIhfIkkZSKQMt6kwgNipEqaq8xYhmMhpuJhu98qxs9Q2SBetQRHxZJ4m7wS+1jZGuQ==","_resolved":"/tmp/a34382185971c48d6b59c145f8860a1a/achado-react-0.0.2.tgz","_from":"file:achado-react-0.0.2.tgz","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-OKmOjebM3VPpjZYDDB7TmIhfIkkZSKQMt6kwgNipEqaq8xYhmMhpuJhu98qxs9Q2SBetQRHxZJ4m7wS+1jZGuQ==","shasum":"8e8f66f9831a47b453454e6107e49fa043588238","tarball":"https://registry.npmjs.org/@achado/react/-/react-0.0.2.tgz","fileCount":41,"unpackedSize":109887,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICiIzN1QcPX2mCEthBHfSC0cZCG5pBY+CiEHWnjselXfAiArnumQGF3s1hd1nXPj/yFhs9Byxd2BkSflAgx03i6ptQ=="}]},"_npmUser":{"name":"achado","email":"achadolabs@gmail.com"},"directories":{},"maintainers":[{"name":"achado","email":"achadolabs@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/react_0.0.2_1759937319180_0.31510468110185896"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-08T11:57:48.703Z","modified":"2025-10-08T15:28:39.487Z","0.0.1":"2025-10-08T11:57:49.042Z","0.0.2":"2025-10-08T15:28:39.343Z"},"bugs":{"url":"https://github.com/achado/js-monorepo/issues"},"author":{"name":"Achado"},"license":"MIT","homepage":"https://github.com/achado/js-monorepo","keywords":["react","analytics","tracking","achado","hooks","components"],"repository":{"type":"git","url":"git+https://github.com/achado/js-monorepo.git","directory":"packages/react"},"description":"React bindings for Achado analytics SDK","maintainers":[{"name":"achado","email":"achadolabs@gmail.com"}],"readme":"# @achado/react\n\nReact bindings for Achado analytics SDK. This package provides React hooks and components that make it easy to integrate Achado analytics into React applications.\n\n## Installation\n\n```bash\nnpm install @achado/react\n# or\npnpm add @achado/react\n# or\nyarn add @achado/react\n```\n\n**Peer Dependencies**: This package requires React 16.8+ (for hooks support).\n\n## Quick Start\n\n### 1. Provider Setup\n\nWrap your app with the `AchadoProvider`:\n\n```tsx\nimport { AchadoProvider } from '@achado/react';\n\nfunction App() {\n return (\n Loading analytics...}\n >\n \n \n );\n}\n```\n\n### 2. Using Hooks\n\n```tsx\nimport { useAchadoTracking, useAchadoUser } from '@achado/react';\n\nfunction UserProfile() {\n const { track, trackClick } = useAchadoTracking();\n const { user, identify } = useAchadoUser();\n\n const handleSignUp = async (userData) => {\n // Identify the user\n identify(userData.id, {\n name: userData.name,\n email: userData.email,\n plan: 'free',\n });\n\n // Track the signup event\n track('user_signed_up', {\n source: 'profile_page',\n plan: userData.plan,\n });\n };\n\n return (\n
\n

Welcome, {user?.traits?.name || 'Guest'}!

\n \n
\n );\n}\n```\n\n## API Reference\n\n### Components\n\n#### `AchadoProvider`\n\nProvides Achado client context to child components.\n\n```tsx\nimport { AchadoProvider } from '@achado/react';\n\n// Option 1: Configuration-based (recommended)\n}\n errorComponent={}\n>\n \n\n\n// Option 2: Client-based (advanced)\n}\n>\n \n\n```\n\n**Props:**\n\n- `config: AchadoConfig` - Achado configuration (alternative to client)\n- `client: AchadoClient` - Pre-initialized client (alternative to config)\n- `loadingComponent?: ReactNode` - Component shown while initializing\n- `errorComponent?: ReactNode` - Component shown on initialization error\n- `children: ReactNode` - Your app components\n\n### Hooks\n\n#### `useAchadoClient()`\n\nAccess the raw Achado client and core methods.\n\n```tsx\nimport { useAchadoClient } from '@achado/react';\n\nfunction MyComponent() {\n const {\n client, // Raw AchadoClient instance\n track, // Track custom events\n identify, // Identify users\n setUserProperties, // Set user properties\n getUser, // Get current user\n flush, // Flush pending events\n reset, // Reset client state\n getQueueStats, // Get queue statistics\n isLoading, // Loading state\n isInitialized, // Initialization state\n } = useAchadoClient();\n\n return
Status: {isLoading ? 'Loading...' : 'Ready'}
;\n}\n```\n\n#### `useAchadoTracking()`\n\nConvenient tracking methods for common events.\n\n```tsx\nimport { useAchadoTracking } from '@achado/react';\n\nfunction MyComponent() {\n const {\n track, // Track any event\n trackPageView, // Track page views\n trackClick, // Track clicks\n trackConversion, // Track conversions\n trackError, // Track errors\n getTrackingCallback, // Get memoized callback\n } = useAchadoTracking();\n\n const handleClick = getTrackingCallback('button_clicked', {\n button_id: 'header-cta',\n location: 'top-nav',\n });\n\n return ;\n}\n```\n\n#### `useAchadoUser()`\n\nUser identification and management.\n\n```tsx\nimport { useAchadoUser } from '@achado/react';\n\nfunction UserProfile() {\n const {\n user, // Current user data\n identify, // Identify user\n setUserProperties, // Set user properties\n updateTraits, // Update user traits\n resetUser, // Reset user data\n getUserProperty, // Get specific property\n getUserTrait, // Get specific trait\n isIdentified, // Is user identified?\n sessionId, // Current session ID\n anonymousId, // Anonymous ID\n } = useAchadoUser();\n\n if (!isIdentified) {\n return ;\n }\n\n return (\n
\n

Hello, {getUserTrait('name')}!

\n

Session: {sessionId}

\n
\n );\n}\n```\n\n#### `useAchadoAnalytics()`\n\nAnalytics utilities and statistics.\n\n```tsx\nimport { useAchadoAnalytics } from '@achado/react';\n\nfunction AnalyticsDashboard() {\n const {\n getStats, // Get analytics stats\n flush, // Flush pending events\n getQueueStats, // Get queue stats\n isReady, // Is client ready?\n sdkVersion, // SDK version\n setDebugMode, // Enable/disable debug\n } = useAchadoAnalytics();\n\n const stats = getStats();\n\n return (\n
\n

Analytics Status

\n

Ready: {isReady ? 'Yes' : 'No'}

\n

SDK Version: {sdkVersion}

\n

Pending Events: {stats.queueStats.pending}

\n \n
\n );\n}\n```\n\n## Advanced Usage\n\n### Server-Side Rendering (SSR)\n\nThe React bindings handle SSR gracefully by deferring client initialization to the browser:\n\n```tsx\n// Next.js example\nimport { AchadoProvider } from '@achado/react';\n\nfunction MyApp({ Component, pageProps }) {\n return (\n Initializing analytics...}\n >\n \n \n );\n}\n```\n\n### Custom Hook Composition\n\nCreate your own specialized hooks:\n\n```tsx\nimport { useAchadoTracking, useAchadoUser } from '@achado/react';\n\nfunction useEcommerceTracking() {\n const { track } = useAchadoTracking();\n const { user } = useAchadoUser();\n\n const trackPurchase = (orderData) => {\n track('purchase', {\n order_id: orderData.id,\n total: orderData.total,\n currency: orderData.currency,\n user_id: user?.userId,\n });\n };\n\n const trackAddToCart = (product) => {\n track('add_to_cart', {\n product_id: product.id,\n product_name: product.name,\n price: product.price,\n });\n };\n\n return { trackPurchase, trackAddToCart };\n}\n```\n\n### Error Boundaries\n\nHandle analytics errors gracefully:\n\n```tsx\nimport { AchadoProvider } from '@achado/react';\n\nfunction App() {\n return (\n Analytics failed to load. App will continue without tracking.\n }\n >\n \n \n );\n}\n```\n\n## TypeScript Support\n\nThis package includes full TypeScript definitions:\n\n```tsx\nimport type {\n AchadoConfig,\n AchadoUser,\n AchadoProviderProps,\n UseAchadoTrackingOutput,\n UseAchadoUserOutput,\n UseAchadoAnalyticsOutput,\n} from '@achado/react';\n\n// All hooks and components are fully typed\nconst trackingHook: UseAchadoTrackingOutput = useAchadoTracking();\n```\n\n## Best Practices\n\n### 1. Provider Placement\n\nPlace the `AchadoProvider` as high as possible in your component tree:\n\n```tsx\n// ✅ Good - High in the tree\n\n \n \n \n\n\n// ❌ Avoid - Too low, limits hook usage\n\n \n \n \n\n```\n\n### 2. Loading States\n\nAlways provide loading components for better UX:\n\n```tsx\n}>\n \n\n```\n\n### 3. Event Batching\n\nThe SDK automatically batches events, but you can manually flush when needed:\n\n```tsx\nfunction usePageTransition() {\n const { flush } = useAchadoAnalytics();\n\n useEffect(() => {\n // Flush events before page unload\n const handleBeforeUnload = () => {\n flush();\n };\n\n window.addEventListener('beforeunload', handleBeforeUnload);\n return () => window.removeEventListener('beforeunload', handleBeforeUnload);\n }, [flush]);\n}\n```\n\n## Examples\n\n- [Basic React App](../../examples/react-app) (coming soon)\n- [Next.js Integration](../../examples/nextjs-app) (coming soon)\n- [E-commerce Tracking](../../examples/ecommerce-react) (coming soon)\n\n## Migration Guide\n\nMigrating from direct client usage:\n\n```tsx\n// Before (direct client)\nimport { AchadoClient } from '@achado/client';\n\nconst client = new AchadoClient({ apiKey: 'key' });\nawait client.initialize();\nclient.track('event');\n\n// After (React bindings)\nimport { AchadoProvider, useAchadoTracking } from '@achado/react';\n\nfunction App() {\n return (\n \n \n \n );\n}\n\nfunction MyComponent() {\n const { track } = useAchadoTracking();\n\n useEffect(() => {\n track('event');\n }, []);\n}\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}