{"_id":"@adkit.so/meta-pixel-next","_rev":"3-48f16b48ff24684140f7b270898526f5","name":"@adkit.so/meta-pixel-next","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@adkit.so/meta-pixel-next","version":"1.0.0","keywords":["meta","facebook","pixel","tracking","analytics","nextjs","next","react","typescript"],"author":"","license":"MIT","_id":"@adkit.so/meta-pixel-next@1.0.0","maintainers":[{"name":"jeannen","email":"nicolas@jeannen.com"}],"homepage":"https://github.com/adkit-so/meta-pixel-next#readme","bugs":{"url":"https://github.com/adkit-so/meta-pixel-next/issues"},"dist":{"shasum":"2ece41eaa62a566b2a4f14d3558a8828f52918f4","tarball":"https://registry.npmjs.org/@adkit.so/meta-pixel-next/-/meta-pixel-next-1.0.0.tgz","fileCount":5,"integrity":"sha512-2ecL6LEPfFH4ZLVBwmM6HjoX886R0lyt/x1/A/0MgnZB1aYc1a9OnDJcAsIIhD463ovldosnZzSQJPwyhvNeDw==","signatures":[{"sig":"MEUCIQCeRwqCcejo14yDy5VH3p5cvfLz5zbT1QxM558Vfb7jFgIgWxqgja3tmiX4Y8ztdQD6rNmKphiHcO+3toYgWp5v1d4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":17729},"main":"./dist/index.mjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs"}},"gitHead":"b6cc3462d55d98db1b41ae5ea482e2e736054bd5","scripts":{"dev":"cd playground && npm run dev -- -p 3333","test":"playwright test --config test/playwright.config.ts","build":"unbuild","prepack":"npm run build","release":"npm run test && npm run build && npm publish --access public","test:ui":"playwright test --config test/playwright.config.ts --ui"},"_npmUser":{"name":"jeannen","email":"nicolas@jeannen.com"},"repository":{"url":"git+https://github.com/adkit-so/meta-pixel-next.git","type":"git"},"_npmVersion":"11.4.2","description":"Next.js integration for Meta Pixel tracking - auto PageView on route changes","directories":{},"_nodeVersion":"23.7.0","dependencies":{"@adkit.so/meta-pixel-react":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"next":"^14.0.0","react":"^18.2.0","unbuild":"^2.0.0","react-dom":"^18.2.0","typescript":"^5.3.3","@types/react":"^18.2.0","@playwright/test":"^1.56.1"},"peerDependencies":{"next":">=13.0.0","react":">=18.0.0"},"_npmOperationalInternal":{"tmp":"tmp/meta-pixel-next_1.0.0_1764137859250_0.8899946385422777","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Renamed to @adkit/meta-pixel-next. Install that instead; the API is unchanged."},"1.0.1":{"name":"@adkit.so/meta-pixel-next","version":"1.0.1","keywords":["meta","facebook","pixel","tracking","analytics","nextjs","next","react","typescript"],"author":"","license":"MIT","_id":"@adkit.so/meta-pixel-next@1.0.1","maintainers":[{"name":"jeannen","email":"nicolas@jeannen.com"}],"homepage":"https://github.com/adkit-so/meta-pixel-next#readme","bugs":{"url":"https://github.com/adkit-so/meta-pixel-next/issues"},"dist":{"shasum":"e83171c99b2c5d5f6ff4e39769da9a63647bf5df","tarball":"https://registry.npmjs.org/@adkit.so/meta-pixel-next/-/meta-pixel-next-1.0.1.tgz","fileCount":5,"integrity":"sha512-T1VcjEW4ll+6IzIgEVPJ5tvKhbnG1St4TVNLS6jCcSXxFV3ASE+xqNFdBWJQdDcRvMfvb0rmJjHr/iF0k48+cA==","signatures":[{"sig":"MEQCIHojiSBQ47GqMWkU+lOlNzAvZvcR7qSt2zFd7zukFn9TAiAzqdIUV4q+z1auFJccFfCYm1kuTgEa5xZfly5dgNeNPg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":17945},"main":"./dist/index.mjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs"}},"gitHead":"dc2be3ebb46d0877d3e5ba0acc2cfc83f6a3bd6d","scripts":{"dev":"cd playground && npm run dev -- -p 3333","test":"playwright test --config test/playwright.config.ts","build":"unbuild","prepack":"npm run build","release":"npm run test && npm run build && npm publish --access public","test:ui":"playwright test --config test/playwright.config.ts --ui"},"_npmUser":{"name":"jeannen","email":"nicolas@jeannen.com"},"repository":{"url":"git+https://github.com/adkit-so/meta-pixel-next.git","type":"git"},"_npmVersion":"11.4.2","description":"Next.js integration for Meta Pixel tracking - auto PageView on route changes","directories":{},"_nodeVersion":"23.7.0","dependencies":{"@adkit.so/meta-pixel-react":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"next":"^14.0.0","react":"^18.2.0","unbuild":"^2.0.0","react-dom":"^18.2.0","typescript":"^5.3.3","@types/react":"^18.2.0","@playwright/test":"^1.56.1"},"peerDependencies":{"next":">=13.0.0","react":">=18.0.0"},"_npmOperationalInternal":{"tmp":"tmp/meta-pixel-next_1.0.1_1764138808715_0.7948626036370774","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Renamed to @adkit/meta-pixel-next. Install that instead; the API is unchanged."}},"time":{"created":"2025-11-26T06:17:39.121Z","modified":"2026-07-30T04:03:51.377Z","1.0.0":"2025-11-26T06:17:39.428Z","1.0.1":"2025-11-26T06:33:28.883Z"},"bugs":{"url":"https://github.com/adkit-so/meta-pixel-next/issues"},"license":"MIT","homepage":"https://github.com/adkit-so/meta-pixel-next#readme","keywords":["meta","facebook","pixel","tracking","analytics","nextjs","next","react","typescript"],"repository":{"url":"git+https://github.com/adkit-so/meta-pixel-next.git","type":"git"},"description":"Next.js integration for Meta Pixel tracking - auto PageView on route changes","maintainers":[{"name":"jeannen","email":"nicolas@jeannen.com"}],"readme":"# Meta Pixel for Next.js\n\n[![npm version](https://img.shields.io/npm/v/@adkit.so/meta-pixel-next.svg)](https://www.npmjs.com/package/@adkit.so/meta-pixel-next)\n[![npm downloads](https://img.shields.io/npm/dm/@adkit.so/meta-pixel-next.svg)](https://www.npmjs.com/package/@adkit.so/meta-pixel-next)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n> The simplest Meta Pixel integration for Next.js — with automatic PageView tracking on route changes.\n\nBuilt on top of [@adkit.so/meta-pixel-react](https://www.npmjs.com/package/@adkit.so/meta-pixel-react), this package provides a drop-in component that handles everything automatically.\n\n## 📚 Table of Contents\n\n-   [Features](#-features)\n-   [Quick Start](#-quick-start)\n-   [Configuration](#️-configuration)\n-   [Manual Event Tracking](#-manual-event-tracking)\n-   [Standard Events](#-standard-events)\n-   [Advanced Usage](#-advanced-usage)\n-   [TypeScript](#-typescript)\n-   [Troubleshooting](#-troubleshooting)\n-   [License](#-license)\n\n## ✨ Features\n\n-   ✅ **Auto PageView on Route Changes** - No manual tracking needed for navigation\n-   🎯 **Simple Drop-in Component** - Just wrap your app with `<MetaPixel />`\n-   🔧 **Environment Variable Support** - Use `NEXT_PUBLIC_META_PIXEL_ID` out of the box\n-   📘 **TypeScript Support** - Full type definitions with autocomplete\n-   🚀 **App Router Ready** - Works with Next.js 13+ App Router\n-   🔌 **Multiple Pixels Support** - Track to multiple pixel IDs effortlessly\n\n## ⚡ Quick Start\n\n```bash\nnpm install @adkit.so/meta-pixel-next\n```\n\nAdd `<MetaPixel />` to your root layout:\n\n```tsx\n// app/layout.tsx\nimport { MetaPixel } from '@adkit.so/meta-pixel-next';\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n    return (\n        <html>\n            <body>\n                <MetaPixel pixelId=\"YOUR_PIXEL_ID\">{children}</MetaPixel>\n            </body>\n        </html>\n    );\n}\n```\n\nTrack events in any component:\n\n```tsx\n'use client';\n\nimport { useMetaPixel } from '@adkit.so/meta-pixel-next';\n\nexport function PurchaseButton() {\n    const meta = useMetaPixel();\n\n    function handlePurchase() {\n        meta.track('Purchase', { value: 99.99, currency: 'USD' });\n    }\n\n    return <button onClick={handlePurchase}>Buy Now</button>;\n}\n```\n\nThat's it! 🎉\n\n## ⚙️ Configuration\n\n### Component Props\n\n| Prop                | Type                 | Default | Description                                                              |\n| ------------------- | -------------------- | ------- | ------------------------------------------------------------------------ |\n| `pixelId`           | `string \\| string[]` | -       | Your Meta Pixel ID(s). Falls back to `NEXT_PUBLIC_META_PIXEL_ID` env var |\n| `debug`             | `boolean`            | `false` | Enable styled console logging                                            |\n| `enableLocalhost`   | `boolean`            | `false` | Enable tracking on localhost (for testing)                               |\n| `autoTrackPageView` | `boolean`            | `true`  | Auto track PageView on initial load and route changes                    |\n\n### Using Environment Variables\n\nInstead of passing `pixelId` as a prop, use an environment variable:\n\n```bash\n# .env.local\nNEXT_PUBLIC_META_PIXEL_ID=123456789012345\n```\n\n```tsx\n// app/layout.tsx\nimport { MetaPixel } from '@adkit.so/meta-pixel-next';\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n    return (\n        <html>\n            <body>\n                <MetaPixel debug={true} enableLocalhost={true}>\n                    {children}\n                </MetaPixel>\n            </body>\n        </html>\n    );\n}\n```\n\n### Multiple Pixels\n\nTrack to multiple pixels simultaneously:\n\n```tsx\n<MetaPixel pixelId={['PIXEL_ID_1', 'PIXEL_ID_2', 'PIXEL_ID_3']}>{children}</MetaPixel>\n```\n\nOr via environment variable (comma-separated):\n\n```bash\nNEXT_PUBLIC_META_PIXEL_ID=PIXEL_1,PIXEL_2\n```\n\n## 💡 Manual Event Tracking\n\nUse the `useMetaPixel` hook in any client component:\n\n```tsx\n'use client';\n\nimport { useMetaPixel } from '@adkit.so/meta-pixel-next';\n\nexport function ProductPage({ product }) {\n    const meta = useMetaPixel();\n\n    function handleAddToCart() {\n        meta.track('AddToCart', {\n            content_ids: [product.id],\n            content_name: product.name,\n            value: product.price,\n            currency: 'USD',\n        });\n    }\n\n    function handlePurchase() {\n        meta.track('Purchase', {\n            content_ids: [product.id],\n            value: product.price,\n            currency: 'USD',\n            num_items: 1,\n        });\n    }\n\n    return (\n        <div>\n            <h1>{product.name}</h1>\n            <button onClick={handleAddToCart}>Add to Cart</button>\n            <button onClick={handlePurchase}>Buy Now</button>\n        </div>\n    );\n}\n```\n\n### Custom Events\n\nTrack custom events specific to your business:\n\n```tsx\nconst meta = useMetaPixel();\n\nfunction trackPricingView() {\n    meta.trackCustom('PricingViewed', {\n        plan: 'enterprise',\n        source: 'homepage_cta',\n    });\n}\n\nfunction trackVideoComplete() {\n    meta.trackCustom('VideoWatched', {\n        video_id: 'intro_2024',\n        watch_percentage: 100,\n    });\n}\n```\n\n### Event Deduplication\n\nPrevent duplicate events using `eventID`:\n\n```tsx\nfunction handleCheckout(orderId: string) {\n    meta.track('Purchase', { value: 299.99, currency: 'USD' }, { eventID: `order-${orderId}` });\n}\n```\n\n## 📊 Standard Events\n\nAll Meta Pixel standard events are supported with full TypeScript autocomplete:\n\n| Event                  | Description                       | Common Use Cases   |\n| ---------------------- | --------------------------------- | ------------------ |\n| `PageView`             | **Auto-tracked** on route changes | -                  |\n| `ViewContent`          | Content/product viewed            | Product pages      |\n| `Search`               | Search performed                  | Site search        |\n| `AddToCart`            | Item added to cart                | E-commerce         |\n| `AddToWishlist`        | Item added to wishlist            | E-commerce         |\n| `InitiateCheckout`     | Checkout started                  | Cart page          |\n| `AddPaymentInfo`       | Payment info added                | Checkout flow      |\n| `Purchase`             | Purchase completed                | Order confirmation |\n| `Lead`                 | Lead form submitted               | Contact forms      |\n| `CompleteRegistration` | Registration completed            | Sign-up flows      |\n| `Contact`              | Contact action                    | Contact page       |\n| `Schedule`             | Appointment scheduled             | Booking systems    |\n| `StartTrial`           | Trial started                     | SaaS apps          |\n| `Subscribe`            | Subscription started              | Newsletters        |\n\n### Event Data Parameters\n\n| Parameter          | Type       | Description            | Example           |\n| ------------------ | ---------- | ---------------------- | ----------------- |\n| `value`            | `number`   | Monetary value         | `99.99`           |\n| `currency`         | `string`   | ISO 4217 currency code | `'USD'`, `'EUR'`  |\n| `content_ids`      | `string[]` | Product IDs or SKUs    | `['SKU_123']`     |\n| `content_type`     | `string`   | Type of content        | `'product'`       |\n| `content_name`     | `string`   | Name of product/page   | `'Blue T-Shirt'`  |\n| `content_category` | `string`   | Category               | `'Apparel'`       |\n| `num_items`        | `number`   | Number of items        | `3`               |\n| `search_string`    | `string`   | Search query           | `'running shoes'` |\n\n## 🚀 Advanced Usage\n\n### Complete E-commerce Example\n\n```tsx\n'use client';\n\nimport { useMetaPixel } from '@adkit.so/meta-pixel-next';\nimport { useEffect } from 'react';\n\nexport function ProductPage({ product }) {\n    const meta = useMetaPixel();\n\n    useEffect(() => {\n        // Track product view on page load\n        meta.track('ViewContent', {\n            content_ids: [product.id],\n            content_type: 'product',\n            content_name: product.name,\n            content_category: product.category,\n            value: product.price,\n            currency: 'USD',\n        });\n    }, [product.id]);\n\n    function handleAddToCart() {\n        meta.track('AddToCart', {\n            content_ids: [product.id],\n            content_type: 'product',\n            content_name: product.name,\n            value: product.price,\n            currency: 'USD',\n        });\n    }\n\n    function handlePurchase(orderId: string) {\n        meta.track(\n            'Purchase',\n            {\n                content_ids: [product.id],\n                content_type: 'product',\n                value: product.price,\n                currency: 'USD',\n                num_items: 1,\n            },\n            { eventID: orderId }, // For deduplication\n        );\n    }\n\n    return (\n        <div>\n            <h1>{product.name}</h1>\n            <p>${product.price}</p>\n            <button onClick={handleAddToCart}>Add to Cart</button>\n            <button onClick={() => handlePurchase('order-123')}>Buy Now</button>\n        </div>\n    );\n}\n```\n\n### Disable Auto PageView Tracking\n\nIf you prefer to handle PageView tracking manually:\n\n```tsx\n<MetaPixel pixelId=\"YOUR_PIXEL_ID\" autoTrackPageView={false}>\n    {children}\n</MetaPixel>\n```\n\n### Check if Pixel is Loaded\n\n```tsx\nfunction trackIfReady() {\n    if (meta.isLoaded()) {\n        meta.track('Purchase', { value: 99.99, currency: 'USD' });\n    }\n}\n```\n\n## 📘 TypeScript\n\nFull TypeScript support with exported types:\n\n```tsx\nimport type { StandardEvent, EventData, EventMetaData } from '@adkit.so/meta-pixel-next';\n\nfunction trackEvent(event: StandardEvent, data: EventData) {\n    meta.track(event, data);\n}\n```\n\n## 🐛 Debug Mode\n\nEnable `debug={true}` to see styled console logs:\n\n```\n[Meta Pixel] Initializing Meta Pixel... { pixelIds: [...] }\n[Meta Pixel] ✓ Meta Pixel initialized successfully\n[Meta Pixel] Tracking: PageView\n[Meta Pixel Next.js] Auto-tracking PageView on route change: /about\n```\n\n## ❓ Troubleshooting\n\n### Pixel not loading?\n\n1. **Check your pixel ID** - Verify it's correct\n2. **Enable debug mode** - Set `debug={true}` to see logs\n3. **Enable localhost** - Set `enableLocalhost={true}` for local testing\n4. **Check browser console** - Look for errors\n\n### PageView not tracking on route changes?\n\nMake sure `<MetaPixel />` wraps your content in the root layout, not a nested layout.\n\n### Events not showing in Meta Events Manager?\n\n-   **Wait 5-20 minutes** - Events can take time to appear\n-   **Use Test Events tool** - In Meta Events Manager\n-   **Check ad blockers** - They can block the pixel\n\n### Using React without Next.js?\n\nUse [@adkit.so/meta-pixel-react](https://www.npmjs.com/package/@adkit.so/meta-pixel-react) instead. Note: auto PageView on route changes requires manual setup with React Router.\n\n## 📖 Full Guide\n\nFor a complete step-by-step guide on installing and configuring Meta Pixel, check out our detailed tutorial:\n\n**[How to Install Meta Pixel](https://adkit.so/resources/how-to-install-meta-pixel)**\n\n## 📚 Official Documentation\n\n-   **[Meta Pixel Reference](https://developers.facebook.com/docs/meta-pixel/reference/)** - Complete API reference\n-   **[Standard Events Guide](https://developers.facebook.com/docs/meta-pixel/implementation/conversion-tracking#standard-events)** - Event documentation\n-   **[Events Manager](https://www.facebook.com/events_manager2)** - Monitor your pixel events\n\n## 📄 License\n\nMIT\n\n---\n\n**Made with ❤️ by [Adkit](https://adkit.so)**\n\nIf this package helped you, please consider giving it a ⭐️ on [GitHub](https://github.com/AdKit-so/meta-pixel-next)!\n","readmeFilename":"README.md"}