Running a Content SDK app behind a corporate proxy

See the official guide from Node.js to configure enterprise networks. You can add the environment variables to the dev script inside package.json or to the .env file.

See the following example to update the dev script:

"dev": "cross-env NODE_ENV=development NODE_USE_ENV_PROXY=1 HTTP_PROXY=http://YOUR_PROXY HTTPS_PROXY=http://YOUR_PROXY npm-run-all --serial sitecore-tools:generate-map sitecore-tools:build --parallel next:dev sitecore-tools:generate-map:watch", 

Another option is to initialize proxy behavior during server startup using Next.js instrumentation. Next.js supports adding an instrumentation.ts|js file at the project root. It contains a register function that runs once when the server starts. This makes it ideal to set up runtime-wide networking behavior before your app begins handling requests.

See the following example of an instrumentation.ts file:

export async function register() {
   if (process.env.NODE_ENV !== "development") return;
   const proxyUrl = process.env.HTTPS_PROXY || process.env.HTTP_PROXY;
   if (!proxyUrl) return;
   const { ProxyAgent, setGlobalDispatcher, install } = await import("undici");
   const dispatcher = new ProxyAgent({
      uri: proxyUrl,
   });
   setGlobalDispatcher(dispatcher);
   install();
}

The register() function runs when the server starts. In this implementation, it only applies proxy configuration in development, based on the NODE_ENV check.

It reads proxy settings from standard environment variables (HTTPS_PROXY or HTTP_PROXY) and, if configured, creates a proxy dispatcher using undici. Calling setGlobalDispatcher(dispatcher) sets this proxy agent as the default dispatcher, ensuring that outgoing requests, including those made with Node.js fetch, are routed through the proxy.

The call to install() ensures that the global fetch implementation is provided by undici and uses the configured dispatcher consistently across the application.

Once you have the instrumentation file, you can add the register function in your sitecore.cli.config.ts file. This allows the CLI to use the proxied fetch from undici.

import { defineCliConfig } from "@sitecore-content-sdk/nextjs/config-cli";

import {
   generateSites,
   generateMetadata,
   extractFiles,
   writeImportMap,
} from "@sitecore-content-sdk/nextjs/tools";

import scConfig from "./sitecore.config";

import { register } from "src/instrumentation";

if (process.env.NODE_ENV === "development") register();

export default defineCliConfig({
   config: scConfig,
   build: {
      commands: [
         generateMetadata(),
         generateSites(),
         extractFiles(),
         writeImportMap({
            paths: ["src/components"],
         }),
      ],
   },
   componentMap: {
      paths: ["src/components"],

      exclude: ["src/components/content-sdk/*"],
   },
});

See Customizing SitecoreClient for more information on extending the default SitecoreClient behavior.