— Next.js SDK

Next.js SDK (sdk-next)

App Router helper that keeps serializable config on the server and initializes the client-only provider in a layout component.

Install

pnpm add @emit-vision/sdk-next
npm install @emit-vision/sdk-next

Why a separate Next.js helper?

Server components can't hold client state — they render on the server and don't participate in the browser event loop. Calling init() directly inside a server component would silently do nothing, or worse, crash at runtime.

createEmitVisionNextConfig produces a plain serializable object on the server (no browser APIs touched). That object is passed as props into <EmitVisionProvider>, a client component that does the real SDK initialization once it reaches the browser.

Wire up the root layout

In your server root layout, call createEmitVisionNextConfig() to build the config, then spread it into <EmitVisionProvider>:

// app/layout.tsx  (server component — no "use client")
import { createEmitVisionNextConfig } from "@emit-vision/sdk-next/server";
import { EmitVisionProvider } from "@emit-vision/sdk-next/client";

const emitVisionConfig = createEmitVisionNextConfig({
  apiKey: process.env.EMIT_VISION_API_KEY,
  environment: process.env.NODE_ENV,
  release: process.env.NEXT_PUBLIC_APP_VERSION ?? "dev",
});

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <EmitVisionProvider {...emitVisionConfig}>
          {children}
        </EmitVisionProvider>
      </body>
    </html>
  );
}

The layout file itself stays a server component. Only EmitVisionProvider (imported from @emit-vision/sdk-next/client) runs in the browser.

Use the hook in client components

Inside any "use client" component that is a descendant of the provider, call useEmitVision(). The API is identical to the sdk-react hook.

"use client";
import { useEmitVision } from "@emit-vision/sdk-next/client";

export function CheckoutButton({ planId }: { planId: string }) {
  const { captureEvent } = useEmitVision();

  return (
    <button
      onClick={() =>
        captureEvent("checkout_started", { plan: planId })
      }
    >
      Start checkout
    </button>
  );
}

Config options

createEmitVisionNextConfig accepts:

  • apiKey — your ingest token (starts with evk_), safe to include in browser bundles.
  • environment — development, staging, or production.
  • release — the version string or git SHA for this build.

For self-hosted deployments, also pass endpoint with your instance URL.

Migration from sdk-react

If you already have <EmitVisionProvider> from sdk-react in a Next.js project, migration is minimal:

  • Replace the import with @emit-vision/sdk-next/client.
  • Move the apiKey / config values into createEmitVisionNextConfig in the server layout.
  • All useEmitVision() call sites in client components stay unchanged.