SPFx Basics: Configure npm for a corporate web proxy

Learn how to configure your development environment for npm to work with corporate web proxies to install npm packages.

By Last Updated: December 7, 2024 2 minutes read

Network switch

Photo by Jordan Harrison on Unsplash

Some organizations deploy a proxy server, also referred to as a corporate web proxy, as part of a gateway server. These proxies separate the corporate network from external networks, including the Internet, as a firewall to protect the internal network.

Not all companies use proxies, but they aren’t uncommon. They’re commonly used to avoid network intrusions and enable scanning of traffic before it’s delivered to the client on the network.

These proxies, while good natured, can frustrate users and developers alike. For example, Node.js and npm assume they aren’t running from behind a corporate web proxy. What’s the implication of this?

SharePoint Framework (SPFx) & corporate proxy servers

Consider if you’re setting up your developer environment for SharePoint Framework development. When installing the prerequisites on your laptop, and installing one of the npm packages, you may run across this error:

> npm install -g yo gulp-cli @microsoft/generator-sharepoint
> npm ERR! code ETIMEDOUT
> npm ERR! errno ETIMEDOUT
> npm ERR! network request to https://registry.npmjs.org/yo failed, reason connect ETIMEDOUT: XXX.XXX.XXX.XXX:443
> npm ERR! network This is a problem related to network connectivity.
> npm ERR! network In most cases you are behind a proxy or have bad network settings.
> npm ERR! network
> npm ERR! network If you are behind a proxy, please make sure that the
> npm ERR! network 'proxy' config is set properly. See: 'npm help config'

Configure npm for corporate proxies

To fix this issue, you need to get the URL of your corporate proxy server.

First, obtain the address of your corporate proxy. For example, let’s assume that’s http://proxy.contoso.com on port 8080. This should match the proxy settings on your workstation’s proxy configuration.

On Windows, you can find that in the Internet Options ➡️ LAN Settings for your connection, under the Proxy server configuration.

On macOS, you can find that in the System Preferences ➡️ Network dialog, select your connection, and then select the Proxies tab.

Then, set the proxy settings for npm in it’s config file by running the following two commands:

npm config set proxy http://proxy.contoso.com:8080
npm config set https-proxy http://proxy.contoso.com:8080

This will update, or create if it doesn’t already exist, the .npmrc configuration file in the root of your profile. npm will use that configuration file when you run it, such as when you try to install npm packages.