Using Fractal with Next.js: Setup and Initialization

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:

// 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.

Get Started

SDK

Guides

Inference

Benchmarks

Training

Troubleshooting

Using Fractal with Next.js: Setup and Initialization

Keep LLM SDKs external

​Keep LLM SDKs external

Keep LLM SDKs external