@signap/signals-nextjs
v2.1.0
Published
SSR-safe Next.js wrapper for @signap/signals-web
Readme
@signap/signals-nextjs
SSR-safe wrapper for @signap/signals-web targeting Next.js 14/15 (App Router).
Install
pnpm add @signap/signals-nextjs
# next/react are peerDependenciesUsage (App Router)
// app/layout.tsx — Server Component
import { SignalsScript } from "@signap/signals-nextjs";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<SignalsScript
apiKey={process.env.NEXT_PUBLIC_SIGNALS_API_KEY!}
endpoint={process.env.NEXT_PUBLIC_SIGNALS_ENDPOINT!}
>
{children}
</SignalsScript>
</body>
</html>
);
}// app/page.tsx — Server Component that contains a Client Component
import { VisitorBadge } from "./visitor-badge";
export default function Page() { return <VisitorBadge />; }// app/visitor-badge.tsx
"use client";
import { useVisitorData } from "@signap/signals-nextjs";
export function VisitorBadge() {
const { data, isLoading } = useVisitorData({ tag: "homepage" });
if (isLoading) return null;
return <span>visitor: {data?.visitorId}</span>;
}v2 (ADR §A2) returns the resolved visitor in a single round-trip — no separate ack/lookup transition. See the
@signap/signals-reactREADME for the full shape.
Endpoint discovery
SignalsScript spreads AgentLoadOptions, so pass an endpoint callback to
resolve the endpoint at runtime — e.g. for region routing. See the
@signap/signals-web README (Endpoint section).
<SignalsScript apiKey={process.env.NEXT_PUBLIC_SIGNALS_API_KEY!} endpoint={async () => (await myConfig()).ingestEndpoint} />SSR-safe contract
@signap/signals-nextjsand@signap/signals-reactimport cleanly into Server Components — module evaluation touches no browser APIs.SignalsScriptcarries the"use client"directive itself; everything reachable from it runs on the client only.- The agent loads inside
useEffect, never during render or hydration. - Public env vars:
NEXT_PUBLIC_*only carry the public apiKey (pk_live_*). Server-only secrets must never appear underNEXT_PUBLIC_.