---
title: "Running a Content SDK app behind a corporate proxy"
slug: "running-a-content-sdk-app-behind-a-corporate-proxy"
abstract: "How to run a Content SDK app behind a corporate proxy."
---
# Running a Content SDK app behind a corporate proxy

Running a Content SDK app behind a corporate network requires handling outbound proxies, custom certificate authorities, and stricter runtime controls. There are three methods for running a Content SDK app behind a corporate proxy:

- Configure Node.js at the environment level
- Initialize proxy behavior early with an instrumentation file
- Customize the `SitecoreClient` directly

## Use Node.js environment configuration (recommended)

See the [official guide from Node.js](https://nodejs.org/learn/http/enterprise-network-configuration) 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:

```text
"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",
```

## Use instrumentation with Undici

Another option is to initialize proxy behavior during server startup using [Next.js instrumentation](https://nextjs.org/docs/app/guides/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:

```ts
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.

```ts
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/*"],
   },
});
```

> [!important]
> Ensure that you consider any customizations you may have in your existing implementation when using the proxied fetch from undici.

## Customizing SitecoreClient

See [Customizing SitecoreClient](https://doc.sitecore.com/sai/en/developers/content-sdk/20/customize-sitecoreclient.html) for more information on extending the default `SitecoreClient` behavior.