{"_id":"@adkit/meta-pixel-next","_rev":"3-0a59164986e0a52aebdcc6b474972404","name":"@adkit/meta-pixel-next","dist-tags":{"latest":"1.1.2"},"versions":{"1.1.0":{"name":"@adkit/meta-pixel-next","version":"1.1.0","keywords":["meta","facebook","pixel","tracking","analytics","nextjs","next","react","typescript"],"author":"","license":"MIT","_id":"@adkit/meta-pixel-next@1.1.0","maintainers":[{"name":"jeannen","email":"nicolas@jeannen.com"}],"homepage":"https://github.com/adkit/ads-tracking#readme","bugs":{"url":"https://github.com/adkit/ads-tracking/issues"},"dist":{"shasum":"51c3291e2bc9dec15fddb689ad818570041093ae","tarball":"https://registry.npmjs.org/@adkit/meta-pixel-next/-/meta-pixel-next-1.1.0.tgz","fileCount":6,"integrity":"sha512-RnITSlIWfkye3KYrjDStwCsp51Z+yfYluLlapNNhx99fkw046LTsvAnP07FhTMuyPvzfrEdKulUiH3RC9/7c1A==","signatures":[{"sig":"MEYCIQDGdgfhumnAdQEpxMepA/GZ3vEWGyJtiWoIo689Qp4gIwIhAI1wgiA/ZGI2zg7CUGQ4puRS9OnodOgdVtyhlrFYatbt","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":19879},"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"}},"scripts":{"dev":"cd playground && npm run dev -- -p 3333","test":"vitest run","build":"unbuild","prepack":"npm run build","test:ui":"playwright test --config test/playwright.config.ts --ui","test:e2e":"playwright test --config test/playwright.config.ts","typecheck":"tsc --noEmit"},"_npmUser":{"name":"jeannen","email":"nicolas@jeannen.com"},"repository":{"url":"git+https://github.com/adkit/ads-tracking.git","type":"git","directory":"packages/meta-pixel-next"},"_npmVersion":"11.4.2","description":"Next.js integration for Meta Pixel tracking - auto PageView on route changes","directories":{},"_nodeVersion":"23.7.0","dependencies":{"@adkit/meta-pixel-react":"^1.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"next":"^14.0.0","react":"^18.2.0","vitest":"^1.0.4","unbuild":"^2.0.0","happy-dom":"^12.10.3","react-dom":"^18.2.0","typescript":"^5.3.3","@types/react":"^18.2.0","@playwright/test":"^1.56.1","@vitejs/plugin-react":"^4.2.1","@testing-library/react":"^14.1.2"},"peerDependencies":{"next":">=13.0.0","react":">=18.0.0"},"_npmOperationalInternal":{"tmp":"tmp/meta-pixel-next_1.1.0_1785327332186_0.8172457578386247","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@adkit/meta-pixel-next","version":"1.1.1","keywords":["meta","facebook","pixel","tracking","analytics","nextjs","next","react","typescript"],"author":"","license":"MIT","_id":"@adkit/meta-pixel-next@1.1.1","maintainers":[{"name":"jeannen","email":"nicolas@jeannen.com"}],"homepage":"https://github.com/adkit/ads-tracking#readme","bugs":{"url":"https://github.com/adkit/ads-tracking/issues"},"dist":{"shasum":"ebc862978e251ca02a22154a03a1ef9154c5cc66","tarball":"https://registry.npmjs.org/@adkit/meta-pixel-next/-/meta-pixel-next-1.1.1.tgz","fileCount":6,"integrity":"sha512-TUdis1fOuhOaVBdpfv+Wxm0ka7oELk+332nxjaEFtaGwK7s/w2eyehypTFLIXNDvH2sOCpDu7u5skvXw3kk+xg==","signatures":[{"sig":"MEUCICMbsp9M/+kjo+e2GUv9T3kpqtInTn05oEsDBHoUEu/mAiEA1gm6hRopVzuBXP8pXxtgWdxJjymZ18HOqNmutC4gckA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":19879},"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":"29c938569d7399ae6110f022e737c4aeaaa3fcae","scripts":{"dev":"cd playground && npm run dev -- -p 3333","test":"vitest run","build":"unbuild","prepack":"npm run build","test:ui":"playwright test --config test/playwright.config.ts --ui","test:e2e":"playwright test --config test/playwright.config.ts","typecheck":"tsc --noEmit"},"_npmUser":{"name":"jeannen","email":"nicolas@jeannen.com"},"repository":{"url":"git+https://github.com/adkit/ads-tracking.git","type":"git","directory":"packages/next/meta-pixel"},"_npmVersion":"11.4.2","description":"Next.js integration for Meta Pixel tracking - auto PageView on route changes","directories":{},"_nodeVersion":"23.7.0","dependencies":{"@adkit/meta-pixel-react":"^1.1.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"next":"^14.0.0","react":"^18.2.0","vitest":"^1.0.4","unbuild":"^2.0.0","happy-dom":"^12.10.3","react-dom":"^18.2.0","typescript":"^5.3.3","@types/react":"^18.2.0","@playwright/test":"^1.56.1","@vitejs/plugin-react":"^4.2.1","@testing-library/react":"^14.1.2"},"peerDependencies":{"next":">=13.0.0","react":">=18.0.0"},"_npmOperationalInternal":{"tmp":"tmp/meta-pixel-next_1.1.1_1785328836750_0.37357110544087324","host":"s3://npm-registry-packages-npm-production"}},"1.1.2":{"name":"@adkit/meta-pixel-next","version":"1.1.2","description":"Meta (Facebook) Pixel for Next.js. Drop-in component with automatic PageView tracking on route changes, App Router support, and lazy script loading.","homepage":"https://adkit.so","repository":{"type":"git","url":"git+https://github.com/adkit/conversion-tracking.git","directory":"packages/next/meta-pixel"},"type":"module","main":"./dist/index.mjs","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.mjs","types":"./dist/index.d.ts"}},"scripts":{"build":"unbuild","typecheck":"tsc --noEmit","dev":"cd playground && npm run dev -- -p 3333","prepack":"npm run build","test":"vitest run","test:e2e":"playwright test --config test/playwright.config.ts","test:ui":"playwright test --config test/playwright.config.ts --ui"},"keywords":["meta-pixel","facebook-pixel","nextjs-facebook-pixel","meta","facebook","pixel","conversion-tracking","tracking","analytics","nextjs","next","react","typescript"],"author":"","license":"MIT","publishConfig":{"access":"public"},"peerDependencies":{"next":">=13.0.0","react":">=18.0.0"},"dependencies":{"@adkit/meta-pixel-react":"^1.1.1"},"devDependencies":{"@playwright/test":"^1.56.1","@testing-library/react":"^14.1.2","@types/react":"^18.2.0","@vitejs/plugin-react":"^4.2.1","happy-dom":"^12.10.3","next":"^14.0.0","react":"^18.2.0","react-dom":"^18.2.0","typescript":"^5.3.3","unbuild":"^2.0.0","vitest":"^1.0.4"},"_id":"@adkit/meta-pixel-next@1.1.2","gitHead":"9088428717b71e58ed944f993ca21544bd7af84b","bugs":{"url":"https://github.com/adkit/conversion-tracking/issues"},"_nodeVersion":"23.7.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-J7OCmwuIMe9de+sfYhOGWvevdFHxPE8c5jJOZkxWOt3QWoQ4JkdmqD0Z/22X0NzRmd97P1I1oPnsOML+zukieA==","shasum":"64efa520e5aed07703487f071275d5c6aecb70be","tarball":"https://registry.npmjs.org/@adkit/meta-pixel-next/-/meta-pixel-next-1.1.2.tgz","fileCount":6,"unpackedSize":20688,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBeJdHrECHekadC0E5jGP9CUqU+Pm5wVvru2bGeqbo3uAiEAvWiom5PTNA01P53kaXz3r2AVuam/mCDnISjajP26x34="}]},"_npmUser":{"name":"jeannen","email":"nicolas@jeannen.com"},"directories":{},"maintainers":[{"name":"jeannen","email":"nicolas@jeannen.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/meta-pixel-next_1.1.2_1785384163144_0.987248210222619"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-29T12:15:32.009Z","modified":"2026-07-30T04:02:43.415Z","1.1.0":"2026-07-29T12:15:32.327Z","1.1.1":"2026-07-29T12:40:36.888Z","1.1.2":"2026-07-30T04:02:43.267Z"},"bugs":{"url":"https://github.com/adkit/conversion-tracking/issues"},"license":"MIT","homepage":"https://adkit.so","keywords":["meta-pixel","facebook-pixel","nextjs-facebook-pixel","meta","facebook","pixel","conversion-tracking","tracking","analytics","nextjs","next","react","typescript"],"repository":{"type":"git","url":"git+https://github.com/adkit/conversion-tracking.git","directory":"packages/next/meta-pixel"},"description":"Meta (Facebook) Pixel for Next.js. Drop-in component with automatic PageView tracking on route changes, App Router support, and lazy script loading.","maintainers":[{"name":"jeannen","email":"nicolas@jeannen.com"}],"readme":"# Meta (Facebook) Pixel for Next.js\n\nAdd the Meta Pixel to your Next.js app with one component and get automatic PageView tracking on route changes. Type-safe events, `NEXT_PUBLIC_META_PIXEL_ID` support, App Router ready, and lazy script loading that keeps fbevents.js off your critical path.\n\n[![npm version](https://img.shields.io/npm/v/@adkit/meta-pixel-next.svg)](https://www.npmjs.com/package/@adkit/meta-pixel-next)\n[![npm downloads](https://img.shields.io/npm/dm/@adkit/meta-pixel-next.svg)](https://www.npmjs.com/package/@adkit/meta-pixel-next)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nBuilt on [@adkit/meta-pixel-react](https://www.npmjs.com/package/@adkit/meta-pixel-react); the `<MetaPixel />` component handles initialization and route tracking for you.\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/meta-pixel-next\n```\n\nAdd `<MetaPixel />` to your root layout:\n\n```tsx\n// app/layout.tsx\nimport { MetaPixel } from '@adkit/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/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| `trackPageViews`    | `boolean`            | `true`  | Auto track PageView on initial load and route changes                    |\n| `loadMode`          | `'eager' \\| 'lazy' \\| 'manual'` | `'eager'` | Choose when to download Meta's vendor script                         |\n\n`lazy` creates Meta's event queue immediately, then downloads the vendor script after the page load and an idle browser opportunity. `manual` creates the queue immediately and waits for `useMetaPixel().load()` to be called. Events sent before the download remain queued.\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/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\n## 💡 Manual Event Tracking\n\nUse the `useMetaPixel` hook in any client component:\n\n```tsx\n'use client';\n\nimport { useMetaPixel } from '@adkit/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/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/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### Does the Facebook Pixel slow down my Next.js app?\n\nfbevents.js is loaded `async`, so it doesn't block HTML parsing. To keep the download out of your Core Web Vitals window entirely, pass `loadMode=\"lazy\"` to `<MetaPixel />`: the event queue is created immediately, but the script only downloads after the page `load` event, at the browser's next idle moment. Events fired in the meantime are queued and sent once the script arrives.\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/meta-pixel-react](https://www.npmjs.com/package/@adkit/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/conversion-tracking)!\n","readmeFilename":"README.md"}