Configuring Environment Variables for SPFx Development

When developing SharePoint Framework (SPFx) solutions, it’s often useful to configure environment variables to manage settings like the SharePoint site URL for testing. This guide will explain different ways to set environment variables in PowerShell and use them effectively in SPFx.

🔹 1. Setting Environment Variables in PowerShell

1.1. Temporary Environment Variable (Session Only)

To set a temporary variable that lasts only during the current terminal session, use:

$env:SPFX_SITE_URL = "https://my-sharepoint-site.sharepoint.com"

This variable will be lost when you close the PowerShell session.

1.2. Permanent Environment Variable (User Scope)

To persist the variable for the current user, run:

[System.Environment]::SetEnvironmentVariable("SPFX_SITE_URL", "https://my-sharepoint-site.sharepoint.com", "User")

1.3. Permanent Environment Variable (Machine Scope)

To set the variable system-wide (requires admin privileges):

[System.Environment]::SetEnvironmentVariable("SPFX_SITE_URL", "https://my-sharepoint-site.sharepoint.com", "Machine")

1.4. Checking Environment Variables

You can verify if the variable is set by running:

$env:SPFX_SITE_URL

1.5. Removing an Environment Variable

• From session: Remove-Item Env:\SPFX_SITE_URL
• Permanently (User Scope): [System.Environment]::SetEnvironmentVariable("SPFX_SITE_URL", $null, "User")
• Permanently (Machine Scope – requires admin): [System.Environment]::SetEnvironmentVariable("SPFX_SITE_URL", $null, "Machine")

🔹 2. Using an .env File in SPFx

Using an .env file allows for easy management of environment variables within the project.

2.1. Create an .env File

In the root of your SPFx project, create a file named .env and add:

SPFX_SITE_URL=https://my-sharepoint-site.sharepoint.com

2.2. Install dotenv to Load the Variables

Since SPFx does not load .env files by default, install dotenv:

npm install dotenv --save-dev

2.3. Modify gulpfile.js to Load the .env File

Open gulpfile.js and add the following code at the top:

const dotenv = require('dotenv');
dotenv.config();

const siteUrl = process.env.SPFX_SITE_URL || "https://default-site.sharepoint.com";
console.log(`Using SharePoint site: ${siteUrl}`);

This ensures that the site URL is loaded from .env when running gulp serve.

🔹 3. Configuring serve.json for Automatic URL Usage

Another way to configure the SharePoint site is by modifying serve.json.

3.1. Locate serve.json

Find the file in config/serve.json and update it as follows:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/serve.schema.json",
  "port": 4321,
  "https": true,
  "initialPage": "https://my-sharepoint-site.sharepoint.com/_layouts/workbench.aspx"
}

This ensures that when you run gulp serve, the browser opens the correct SharePoint Workbench site.

🔹 4. Running gulp serve with a Custom Site

Once you’ve set up the environment variables, you can use them when running gulp serve. There are three ways to do this:

4.1. Manually Passing the Site URL in PowerShell

Instead of modifying files, you can pass the site URL directly in PowerShell before running gulp serve:

$env:SPFX_SITE_URL = "https://my-sharepoint-site.sharepoint.com"
gulp serve

4.2. Using .env File (Recommended)

If you’ve set up .env and modified gulpfile.js, simply run:

gulp serve

4.3. Using serve.json

If you’ve modified serve.json, just execute:

gulp serve

This will open the correct SharePoint Workbench automatically.

Conclusion

Setting up environment variables for SPFx helps streamline development and testing. The best approach depends on your needs:

✅ For quick tests: Set environment variables in PowerShell ($env:SPFX_SITE_URL).

✅ For long-term projects: Use an .env file with dotenv.

✅ For automatic browser opening: Modify serve.json.