@guidelytech/nextjs

Next.js App Router helpers. Re-exports everything from @guidelytech/react and adds the explicit route-change bridge.

pnpm add @guidelytech/nextjs

// app/providers.tsx
"use client";
import { GuidelyProvider, GuidelyNavigationListener, guidelyEnv } from "@guidelytech/nextjs";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <GuidelyProvider
      projectId={process.env.NEXT_PUBLIC_GUIDELY_PROJECT_ID!}
      environment={process.env.NEXT_PUBLIC_GUIDELY_ENV as "development"}
      apiUrl={process.env.NEXT_PUBLIC_GUIDELY_API_URL}
    >
      <GuidelyNavigationListener />
      {children}
    </GuidelyProvider>
  );
}

| Export | Description | |---|---| | GuidelyNavigationListener | Client component using usePathname/useSearchParams (wrapped in Suspense) to call client.page() on every route change. sdk-core also detects History API navigation; this is the explicit bridge. | | guidelyEnv(env?) | Reads NEXT_PUBLIC_GUIDELY_PROJECT_ID, NEXT_PUBLIC_GUIDELY_ENV, NEXT_PUBLIC_GUIDELY_API_URL, NEXT_PUBLIC_GUIDELY_RELEASE into provider props (release selects the source maps uploaded with @guidelytech/sourcemaps). Note: Next.js inlines process.env.NEXT_PUBLIC_* only when referenced literally, so pass them explicitly in your own code as shown above. | | everything from @guidelytech/react | GuidelyProvider, useGuidely, useGuidelyReady, useGuidelyIdentify, useGuidelyEvent, useChecklistProgress, useGuideState, the flag hooks (useFlag, useFeatureValue, useFlagDetails, useFlags, useFlagsReady, useFlagsClient), <Feature>, <FeatureValue>, <FlagsProvider>. |

The built output carries a "use client" banner; import it only from client components.

Feature flags on the server — @guidelytech/nextjs/server

No React and no "use client": works in Server Components, route handlers, server actions and middleware. The same public key as the browser works with no extra configuration.

// app/layout.tsx (Server Component)
import { getFlagsBootstrap } from "@guidelytech/nextjs/server";

export default async function RootLayout({ children }) {
  const flagsPayload = await getFlagsBootstrap(); // the browser starts from this: no flicker
  return <html><body><Providers flagsPayload={flagsPayload}>{children}</Providers></body></html>;
}
// app/providers.tsx ("use client"): <GuidelyProvider … flagsPayload={flagsPayload} user={user}>

// app/checkout/page.tsx, a route handler or a server action
import { getFlags } from "@guidelytech/nextjs/server";

const flags = await getFlags({ id: user.id, plan: user.plan });
if (flags.isEnabled("new-checkout")) …
const color = flags.getString("checkout-button-color", "blue");

| Export | Description | |---|---| | createServerFlags(options?) | The process-wide flags client, created once and kept on globalThis (survives dev hot reloads). Options default to GUIDELY_SDK_KEY (a pk_… or server-only gly_sk_… key) or NEXT_PUBLIC_GUIDELY_PROJECT_ID, GUIDELY_API_URL / NEXT_PUBLIC_GUIDELY_API_URL, GUIDELY_ENV / NEXT_PUBLIC_GUIDELY_ENV. Polls every 60 s; fetches bypass the Next.js data cache. | | getFlags(attributes, { client?, timeoutMs? }) | Getters bound to one user (isEnabled, getValue, getString, getDetails, getAll…). Waits up to timeoutMs (1500) for the first download, then serves fallbacks. | | getFlagsBootstrap({ client?, timeoutMs? }) | The payload for <GuidelyProvider flagsPayload> / <FlagsProvider payload>. null for a gly_sk_ client (its payload contains server-only flags) — bootstrap from a public-key client. |

Evaluate with the attributes the browser will have — the provider's user (id, traits, account) plus flagAttributes — so server-rendered values and hydration agree. Anonymous visitors have no id on the server, so percentage rollouts and experiments keyed on id resolve in the browser (with the visitor's anonymous id) after hydration.

Middleware and edge functions are short-lived: refresh on read instead of polling.

// middleware.ts
import { createServerFlags, getFlags } from "@guidelytech/nextjs/server";
const client = createServerFlags({ pollingMode: "lazy", cacheTtlSeconds: 30 });
export async function middleware(req) {
  const flags = await getFlags({ id: req.cookies.get("uid")?.value }, { client });
  if (flags.isEnabled("maintenance-mode")) return Response.redirect(new URL("/maintenance", req.url));
}