npm - @serge-ai/nextjs - Versions diffs - 0.2.0 - Mend

@serge-ai/nextjs 0.2.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.

Files changed (9) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Superstellar LLC
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,81 @@
+# @serge-ai/nextjs
+> **No cookies. No localStorage by default. No consent banner required.** ePrivacy Art. 5(3) compliant by construction.
+Next.js App Router integration for [Serge](https://serge.ai). Drop-in `<Analytics />` + `<DetectionPixel />` with automatic pageview emission on every route change via `usePathname` / `useSearchParams`.
+```sh
+pnpm add @serge-ai/nextjs
+# or
+npm install @serge-ai/nextjs
+```
+If you're not using the App Router → use **[`@serge-ai/react`](https://www.npmjs.com/package/@serge-ai/react)** instead. Pages Router's `next/router` events handle what we'd need.
+## Quick start
+```tsx
+// app/layout.tsx
+import { Analytics, DetectionPixel } from '@serge-ai/nextjs'
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics token="srg_pub_xxxxxxxxxxxxxxxxxxxxxxxxxx" />
+        <DetectionPixel token="srg_pub_xxxxxxxxxxxxxxxxxxxxxxxxxx" />
+      </body>
+    </html>
+  )
+}
+```
+That's it. Every route change in your app fires a `pageview` automatically; non-JS agents get caught by the pixel.
+To emit a custom event from any client component:
+```tsx
+'use client'
+import { track } from '@serge-ai/nextjs'
+export function CheckoutButton() {
+  return (
+    <button onClick={() => track('checkout_started', { plan: 'pro' })}>
+      Check out
+    </button>
+  )
+}
+```
+## What this does that `@serge-ai/react` doesn't
+- Listens to `usePathname()` + `useSearchParams()` to fire `pageview()` on every App Router navigation. The plain React `<Analytics />` relies on the History API, which Next.js intercepts in ways that can hide route changes from a generic listener.
+- Wraps the search-params listener in `<Suspense>` as Next.js requires — `useSearchParams` forces dynamic rendering of its non-Suspense parent, which would defeat static rendering for the entire layout. The internal Suspense fallback is `null`, so the page tree is visually identical.
+## API re-exports
+```tsx
+import { init, track, consent, pageview, DetectionPixel } from '@serge-ai/nextjs'
+```
+These are re-exports from `@serge-ai/js` and `@serge-ai/react` so consumers can import everything from one path. See **[`@serge-ai/js` docs](https://www.npmjs.com/package/@serge-ai/js)** for the full reference.
+## SSR safety
+Every browser-API access is guarded inside `useEffect`. The component is marked `'use client'`. Safe to import from a server component layout — the `Suspense` wrapper isolates the dynamic-rendering bailout to the inner zero-DOM component.
+## Next.js + React versions
+- `next@>=14` (peer dependency)
+- `react@^18 || ^19` (peer dependency)
+Works in App Router projects. Pages Router → use [`@serge-ai/react`](https://www.npmjs.com/package/@serge-ai/react).
+## Bundle size
+Under 6 KB gzipped (excluding `react`, `next`, `@serge-ai/js`, and `@serge-ai/react`, which the host already provides). [`size-limit`](https://github.com/ai/size-limit) enforces this in CI.
+## License
+MIT © Superstellar LLC. See [LICENSE](./LICENSE).

package/dist/index.cjs ADDED Viewed

@@ -0,0 +1,3 @@
+"use client";
+'use strict';var react$1=require('react'),navigation_js=require('next/navigation.js'),js=require('@serge-ai/js'),react=require('@serge-ai/react'),jsxRuntime=require('react/jsx-runtime');function u({token:e,...o}){let i=navigation_js.usePathname(),r=navigation_js.useSearchParams();return react$1.useEffect(()=>{js.init(e,o);},[e]),react$1.useEffect(()=>{typeof window>"u"||js.pageview();},[i,r?.toString()]),null}function h(e){return jsxRuntime.jsx(react$1.Suspense,{fallback:null,children:jsxRuntime.jsx(u,{...e})})}Object.defineProperty(exports,"consent",{enumerable:true,get:function(){return js.consent}});Object.defineProperty(exports,"init",{enumerable:true,get:function(){return js.init}});Object.defineProperty(exports,"pageview",{enumerable:true,get:function(){return js.pageview}});Object.defineProperty(exports,"track",{enumerable:true,get:function(){return js.track}});Object.defineProperty(exports,"DetectionPixel",{enumerable:true,get:function(){return react.DetectionPixel}});exports.Analytics=h;//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"sources":["../src/index.tsx"],"names":["AnalyticsInner","token","options","pathname","usePathname","search","useSearchParams","useEffect","init","pageview","Analytics","props","jsx","Suspense"],"mappings":"0LA4DA,SAASA,CAAAA,CAAe,CAAE,MAAAC,CAAAA,CAAO,GAAGC,CAAQ,CAAA,CAAyB,CACnE,IAAMC,CAAAA,CAAWC,yBAAAA,GACXC,CAAAA,CAASC,6BAAAA,GAGf,OAAAC,iBAAAA,CAAU,IAAM,CACdC,OAAAA,CAAKP,EAAOC,CAAO,EAErB,EAAG,CAACD,CAAK,CAAC,CAAA,CASVM,iBAAAA,CAAU,IAAM,CACV,OAAO,OAAW,GAAA,EACtBE,WAAAA,GAEF,CAAA,CAAG,CAACN,EAAUE,CAAAA,EAAQ,QAAA,EAAU,CAAC,CAAA,CAE1B,IACT,CAcO,SAASK,EAAUC,CAAAA,CAA6B,CACrD,OACEC,cAAAA,CAACC,gBAAAA,CAAA,CAAS,QAAA,CAAU,IAAA,CAClB,SAAAD,cAAAA,CAACZ,CAAAA,CAAA,CAAgB,GAAGW,CAAAA,CAAO,EAC7B,CAEJ","file":"index.cjs","sourcesContent":["/**\n * @serge-ai/nextjs — Next.js App Router integration.\n *\n * Drop both into `app/layout.tsx` once:\n *\n * import { Analytics, DetectionPixel } from '@serge-ai/nextjs'\n *\n * export default function RootLayout({ children }) {\n * return (\n * <html>\n * <body>\n * {children}\n * <Analytics token=\"srg_pub_xxx\" />\n * <DetectionPixel token=\"srg_pub_xxx\" />\n * </body>\n * </html>\n * )\n * }\n *\n * What `<Analytics />` does that the plain React component doesn't:\n * - Listens to `usePathname()` + `useSearchParams()` to fire a\n * manual `pageview()` on every App Router navigation. The plain\n * React component relies on the History API, which Next.js\n * intercepts in ways that can hide route changes from a generic\n * listener.\n * - Wraps the search-params listener in `<Suspense>` as Next.js\n * requires — `useSearchParams` forces dynamic rendering of its\n * non-Suspense parent, which would defeat static rendering for\n * the entire layout. The fallback is `null` so the page tree is\n * visually identical.\n *\n * `<DetectionPixel />` is the same pixel from `@serge-ai/react`\n * — re-exported here so consumers only need a single import path.\n *\n * Pages Router users should keep using `@serge-ai/react`'s\n * `<Analytics />`; Next's `<Router>` events handle what we'd need.\n */\n\n'use client'\n\nimport { Suspense, useEffect } from 'react'\nimport { usePathname, useSearchParams } from 'next/navigation.js'\nimport {\n init,\n pageview,\n track,\n consent,\n type InitOptions,\n type ConsentValue,\n} from '@serge-ai/js'\nimport { DetectionPixel, type DetectionPixelProps } from '@serge-ai/react'\n\nexport { init, track, consent, pageview, DetectionPixel }\nexport type { InitOptions, ConsentValue, DetectionPixelProps }\n\nexport interface AnalyticsProps extends InitOptions {\n /** Public token from the Serge dashboard (`srg_pub_*`). */\n token: string\n}\n\nfunction AnalyticsInner({ token, ...options }: AnalyticsProps): null {\n const pathname = usePathname()\n const search = useSearchParams()\n\n /* One-time init on mount. Same pattern as the plain React component. */\n useEffect(() => {\n init(token, options)\n /* eslint-disable-next-line react-hooks/exhaustive-deps */\n }, [token])\n\n /* App Router fires usePathname/useSearchParams updates on every\n * navigation. Emit a pageview event so the timeline is accurate.\n * The core `pageview()` is a no-op until init() finishes; the\n * effect order here (init mounted before navigation effects)\n * means the first navigation after mount is captured by the\n * regular session_start path, not by this effect. Subsequent\n * navigations route through here. */\n useEffect(() => {\n if (typeof window === 'undefined') return\n pageview()\n /* eslint-disable-next-line react-hooks/exhaustive-deps */\n }, [pathname, search?.toString()])\n\n return null\n}\n\n/**\n * Next.js App Router wrapper. Wraps the inner component in `<Suspense>`\n * because `useSearchParams` triggers dynamic-rendering bailout on its\n * nearest non-Suspense parent, which would force the whole layout into\n * dynamic rendering on every request. With Suspense it only bails out\n * the (zero-DOM) inner component, preserving static rendering for the\n * rest of the page.\n *\n * The component returns null at runtime — the React 19 / 18 ReactNode\n * incompatibility around children typing is sidestepped by a single\n * cast (Vercel uses the same trick in @vercel/analytics/next).\n */\nexport function Analytics(props: AnalyticsProps): null {\n return (\n <Suspense fallback={null}>\n <AnalyticsInner {...props} />\n </Suspense>\n ) as never\n}\n"]}

package/dist/index.d.cts ADDED Viewed

@@ -0,0 +1,61 @@
+import { InitOptions } from '@serge-ai/js';
+export { ConsentValue, InitOptions, consent, init, pageview, track } from '@serge-ai/js';
+export { DetectionPixel, DetectionPixelProps } from '@serge-ai/react';
+/**
+ * @serge-ai/nextjs — Next.js App Router integration.
+ *
+ * Drop both into `app/layout.tsx` once:
+ *
+ *   import { Analytics, DetectionPixel } from '@serge-ai/nextjs'
+ *
+ *   export default function RootLayout({ children }) {
+ *     return (
+ *       <html>
+ *         <body>
+ *           {children}
+ *           <Analytics token="srg_pub_xxx" />
+ *           <DetectionPixel token="srg_pub_xxx" />
+ *         </body>
+ *       </html>
+ *     )
+ *   }
+ *
+ * What `<Analytics />` does that the plain React component doesn't:
+ *   - Listens to `usePathname()` + `useSearchParams()` to fire a
+ *     manual `pageview()` on every App Router navigation. The plain
+ *     React component relies on the History API, which Next.js
+ *     intercepts in ways that can hide route changes from a generic
+ *     listener.
+ *   - Wraps the search-params listener in `<Suspense>` as Next.js
+ *     requires — `useSearchParams` forces dynamic rendering of its
+ *     non-Suspense parent, which would defeat static rendering for
+ *     the entire layout. The fallback is `null` so the page tree is
+ *     visually identical.
+ *
+ * `<DetectionPixel />` is the same pixel from `@serge-ai/react`
+ * — re-exported here so consumers only need a single import path.
+ *
+ * Pages Router users should keep using `@serge-ai/react`'s
+ * `<Analytics />`; Next's `<Router>` events handle what we'd need.
+ */
+interface AnalyticsProps extends InitOptions {
+    /** Public token from the Serge dashboard (`srg_pub_*`). */
+    token: string;
+}
+/**
+ * Next.js App Router wrapper. Wraps the inner component in `<Suspense>`
+ * because `useSearchParams` triggers dynamic-rendering bailout on its
+ * nearest non-Suspense parent, which would force the whole layout into
+ * dynamic rendering on every request. With Suspense it only bails out
+ * the (zero-DOM) inner component, preserving static rendering for the
+ * rest of the page.
+ *
+ * The component returns null at runtime — the React 19 / 18 ReactNode
+ * incompatibility around children typing is sidestepped by a single
+ * cast (Vercel uses the same trick in @vercel/analytics/next).
+ */
+declare function Analytics(props: AnalyticsProps): null;
+export { Analytics, type AnalyticsProps };

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,61 @@
+import { InitOptions } from '@serge-ai/js';
+export { ConsentValue, InitOptions, consent, init, pageview, track } from '@serge-ai/js';
+export { DetectionPixel, DetectionPixelProps } from '@serge-ai/react';
+/**
+ * @serge-ai/nextjs — Next.js App Router integration.
+ *
+ * Drop both into `app/layout.tsx` once:
+ *
+ *   import { Analytics, DetectionPixel } from '@serge-ai/nextjs'
+ *
+ *   export default function RootLayout({ children }) {
+ *     return (
+ *       <html>
+ *         <body>
+ *           {children}
+ *           <Analytics token="srg_pub_xxx" />
+ *           <DetectionPixel token="srg_pub_xxx" />
+ *         </body>
+ *       </html>
+ *     )
+ *   }
+ *
+ * What `<Analytics />` does that the plain React component doesn't:
+ *   - Listens to `usePathname()` + `useSearchParams()` to fire a
+ *     manual `pageview()` on every App Router navigation. The plain
+ *     React component relies on the History API, which Next.js
+ *     intercepts in ways that can hide route changes from a generic
+ *     listener.
+ *   - Wraps the search-params listener in `<Suspense>` as Next.js
+ *     requires — `useSearchParams` forces dynamic rendering of its
+ *     non-Suspense parent, which would defeat static rendering for
+ *     the entire layout. The fallback is `null` so the page tree is
+ *     visually identical.
+ *
+ * `<DetectionPixel />` is the same pixel from `@serge-ai/react`
+ * — re-exported here so consumers only need a single import path.
+ *
+ * Pages Router users should keep using `@serge-ai/react`'s
+ * `<Analytics />`; Next's `<Router>` events handle what we'd need.
+ */
+interface AnalyticsProps extends InitOptions {
+    /** Public token from the Serge dashboard (`srg_pub_*`). */
+    token: string;
+}
+/**
+ * Next.js App Router wrapper. Wraps the inner component in `<Suspense>`
+ * because `useSearchParams` triggers dynamic-rendering bailout on its
+ * nearest non-Suspense parent, which would force the whole layout into
+ * dynamic rendering on every request. With Suspense it only bails out
+ * the (zero-DOM) inner component, preserving static rendering for the
+ * rest of the page.
+ *
+ * The component returns null at runtime — the React 19 / 18 ReactNode
+ * incompatibility around children typing is sidestepped by a single
+ * cast (Vercel uses the same trick in @vercel/analytics/next).
+ */
+declare function Analytics(props: AnalyticsProps): null;
+export { Analytics, type AnalyticsProps };

package/dist/index.js ADDED Viewed

@@ -0,0 +1,3 @@
+"use client";
+import {Suspense,useEffect}from'react';import {usePathname,useSearchParams}from'next/navigation.js';import {init,pageview}from'@serge-ai/js';export{consent,init,pageview,track}from'@serge-ai/js';export{DetectionPixel}from'@serge-ai/react';import {jsx}from'react/jsx-runtime';function u({token:e,...o}){let i=usePathname(),r=useSearchParams();return useEffect(()=>{init(e,o);},[e]),useEffect(()=>{typeof window>"u"||pageview();},[i,r?.toString()]),null}function h(e){return jsx(Suspense,{fallback:null,children:jsx(u,{...e})})}export{h as Analytics};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"sources":["../src/index.tsx"],"names":["AnalyticsInner","token","options","pathname","usePathname","search","useSearchParams","useEffect","init","pageview","Analytics","props","jsx","Suspense"],"mappings":"mRA4DA,SAASA,CAAAA,CAAe,CAAE,MAAAC,CAAAA,CAAO,GAAGC,CAAQ,CAAA,CAAyB,CACnE,IAAMC,CAAAA,CAAWC,WAAAA,GACXC,CAAAA,CAASC,eAAAA,GAGf,OAAAC,SAAAA,CAAU,IAAM,CACdC,IAAAA,CAAKP,EAAOC,CAAO,EAErB,EAAG,CAACD,CAAK,CAAC,CAAA,CASVM,SAAAA,CAAU,IAAM,CACV,OAAO,OAAW,GAAA,EACtBE,QAAAA,GAEF,CAAA,CAAG,CAACN,EAAUE,CAAAA,EAAQ,QAAA,EAAU,CAAC,CAAA,CAE1B,IACT,CAcO,SAASK,EAAUC,CAAAA,CAA6B,CACrD,OACEC,GAAAA,CAACC,QAAAA,CAAA,CAAS,QAAA,CAAU,IAAA,CAClB,SAAAD,GAAAA,CAACZ,CAAAA,CAAA,CAAgB,GAAGW,CAAAA,CAAO,EAC7B,CAEJ","file":"index.js","sourcesContent":["/**\n * @serge-ai/nextjs — Next.js App Router integration.\n *\n * Drop both into `app/layout.tsx` once:\n *\n * import { Analytics, DetectionPixel } from '@serge-ai/nextjs'\n *\n * export default function RootLayout({ children }) {\n * return (\n * <html>\n * <body>\n * {children}\n * <Analytics token=\"srg_pub_xxx\" />\n * <DetectionPixel token=\"srg_pub_xxx\" />\n * </body>\n * </html>\n * )\n * }\n *\n * What `<Analytics />` does that the plain React component doesn't:\n * - Listens to `usePathname()` + `useSearchParams()` to fire a\n * manual `pageview()` on every App Router navigation. The plain\n * React component relies on the History API, which Next.js\n * intercepts in ways that can hide route changes from a generic\n * listener.\n * - Wraps the search-params listener in `<Suspense>` as Next.js\n * requires — `useSearchParams` forces dynamic rendering of its\n * non-Suspense parent, which would defeat static rendering for\n * the entire layout. The fallback is `null` so the page tree is\n * visually identical.\n *\n * `<DetectionPixel />` is the same pixel from `@serge-ai/react`\n * — re-exported here so consumers only need a single import path.\n *\n * Pages Router users should keep using `@serge-ai/react`'s\n * `<Analytics />`; Next's `<Router>` events handle what we'd need.\n */\n\n'use client'\n\nimport { Suspense, useEffect } from 'react'\nimport { usePathname, useSearchParams } from 'next/navigation.js'\nimport {\n init,\n pageview,\n track,\n consent,\n type InitOptions,\n type ConsentValue,\n} from '@serge-ai/js'\nimport { DetectionPixel, type DetectionPixelProps } from '@serge-ai/react'\n\nexport { init, track, consent, pageview, DetectionPixel }\nexport type { InitOptions, ConsentValue, DetectionPixelProps }\n\nexport interface AnalyticsProps extends InitOptions {\n /** Public token from the Serge dashboard (`srg_pub_*`). */\n token: string\n}\n\nfunction AnalyticsInner({ token, ...options }: AnalyticsProps): null {\n const pathname = usePathname()\n const search = useSearchParams()\n\n /* One-time init on mount. Same pattern as the plain React component. */\n useEffect(() => {\n init(token, options)\n /* eslint-disable-next-line react-hooks/exhaustive-deps */\n }, [token])\n\n /* App Router fires usePathname/useSearchParams updates on every\n * navigation. Emit a pageview event so the timeline is accurate.\n * The core `pageview()` is a no-op until init() finishes; the\n * effect order here (init mounted before navigation effects)\n * means the first navigation after mount is captured by the\n * regular session_start path, not by this effect. Subsequent\n * navigations route through here. */\n useEffect(() => {\n if (typeof window === 'undefined') return\n pageview()\n /* eslint-disable-next-line react-hooks/exhaustive-deps */\n }, [pathname, search?.toString()])\n\n return null\n}\n\n/**\n * Next.js App Router wrapper. Wraps the inner component in `<Suspense>`\n * because `useSearchParams` triggers dynamic-rendering bailout on its\n * nearest non-Suspense parent, which would force the whole layout into\n * dynamic rendering on every request. With Suspense it only bails out\n * the (zero-DOM) inner component, preserving static rendering for the\n * rest of the page.\n *\n * The component returns null at runtime — the React 19 / 18 ReactNode\n * incompatibility around children typing is sidestepped by a single\n * cast (Vercel uses the same trick in @vercel/analytics/next).\n */\nexport function Analytics(props: AnalyticsProps): null {\n return (\n <Suspense fallback={null}>\n <AnalyticsInner {...props} />\n </Suspense>\n ) as never\n}\n"]}

package/package.json ADDED Viewed

@@ -0,0 +1,78 @@
+{
+  "name": "@serge-ai/nextjs",
+  "version": "0.2.0",
+  "description": "Serge for Next.js — App Router-aware <Analytics /> + <DetectionPixel /> with auto pageview tracking on route changes.",
+  "license": "MIT",
+  "homepage": "https://serge.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SuperstellarLLC/heyserge.git",
+    "directory": "packages/nextjs"
+  },
+  "bugs": {
+    "url": "https://github.com/SuperstellarLLC/heyserge/issues"
+  },
+  "keywords": [
+    "next",
+    "nextjs",
+    "next.js",
+    "vercel",
+    "analytics",
+    "tracking",
+    "agent",
+    "ai-agent",
+    "ssr",
+    "cookieless",
+    "app-router"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@serge-ai/js": "0.2.0",
+    "@serge-ai/react": "0.2.0"
+  },
+  "peerDependencies": {
+    "next": ">=14",
+    "react": "^18 || ^19"
+  },
+  "devDependencies": {
+    "@size-limit/preset-small-lib": "^11.1.0",
+    "@types/react": "^19.0.0",
+    "next": "^16.1.6",
+    "react": "^19.0.0",
+    "size-limit": "^11.1.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.8.2",
+    "vitest": "^3.1.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --config ./vitest.config.ts --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "size": "size-limit"
+  }
+}