> ## Documentation Index
> Fetch the complete documentation index at: https://docs.belvedir.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Fractal with Next.js: Setup and Initialization

> Learn how to add Fractal tracing to your Next.js app with the correct initialization order for both server and Edge runtime environments.

The SDK patches your LLM client the moment `initialize()` runs, so it must run **before the LLM SDK is imported**. In Next.js the only place that's guaranteed is the `instrumentation.ts` hook at your project root:

```ts theme={null}
// instrumentation.ts  (project root)
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { initialize } = await import("@fractalresearch/loop");
    const openai = await import("openai");
    const anthropic = await import("@anthropic-ai/sdk");
    initialize({
      apiKey: process.env.FRACTAL_API_KEY,
      appName: "my-ai-app",
      instrumentModules: { openAI: openai.OpenAI, anthropic },
    });
  }
}
```

Do **not** call `initialize()` from inside a route file — by then the LLM SDK is already imported and the patch won't take. In Next.js, always pass `instrumentModules` (only the SDKs you actually use): bundlers can load LLM SDKs in ways auto-instrumentation can't see, which silently drops all LLM spans.

## Keep LLM SDKs external

Also keep the LLM SDKs external so every bundle shares one runtime copy — if they get inlined, each bundle has its own private copy and `instrumentModules` patches one your routes never use. Mind the version-specific config key: on Next 15+ it's top-level `serverExternalPackages`; on Next 13/14 it's `experimental.serverComponentsExternalPackages` — the Next 15 name is silently ignored there (the build prints an `Unrecognized key(s)` warning; don't ignore it).

Requires `@fractalresearch/loop@0.1.3` or later.