@getfluxly/next

Next.js SDK

App Router-native wiring for GetFluxly. Drop-in <GFluxScript> for client autocapture, server-side track / identify / alias for Server Actions and Route Handlers, and a middleware wrapper that forwards client IP / geo into downstream handlers.

Install

npm install @getfluxly/next @getfluxly/react @getfluxly/browser @getfluxly/node

The three sibling packages are peers, the Next SDK doesn't re-bundle them.

Mount the script tag

// app/layout.tsx
import { GFluxScript } from "@getfluxly/next/client";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <GFluxScript apiKey={process.env.NEXT_PUBLIC_GFLUX_API_KEY} />
      </body>
    </html>
  );
}

<GFluxScript> wraps next/script with strategy="afterInteractive" by default. Set strategy="lazyOnload" if you want to defer past hydration.

Track from a Server Action

// app/actions/subscribe.ts
"use server";
import { track } from "@getfluxly/next/server";

export async function subscribe(plan: string, userId: string) {
  await track("subscription_started", {
    externalId: userId,
    properties: { plan },
  });
}

track, identify, and alias are auto-flushed, the function is short-lived in serverless runtimes, so the SDK fires immediately rather than batching.

The /server subpath is gated by the "node" export condition. Importing it from a client component fails the Next build instead of leaking your server token into the browser.

Required env

| Var | Where | Notes | | --- | --- | --- | | NEXT_PUBLIC_GFLUX_API_KEY | client + server | Publishable key | | GFLUX_SERVER_TOKEN | server only | Server key | | NEXT_PUBLIC_GFLUX_API_HOST | optional | Defaults to https://api.getfluxly.com |

Use the gfluxEnv() helper from @getfluxly/next if you want type-safe reads with required-var assertions.

Middleware

// middleware.ts
import { withGFluxMiddleware } from "@getfluxly/next/middleware";

export default withGFluxMiddleware(
  async (req) => {
    // Your middleware logic here.
  },
  { forwardIp: true, forwardGeo: true },
);

The wrapper attaches x-gflux-ip, x-gflux-country, x-gflux-region headers to downstream Server Components and Route Handlers so server-side track() calls can enrich event context with the customer's network identity.