spfx-env

⚠️ Breaking Change In 2.0.0

From version 2.0.0, spfx-env supports only Heft-based SPFx projects.

If your project still uses gulp-based SPFx build tooling, stay on a 1.x version of spfx-env.

spfx-env is a CLI utility to automate environment setup and configuration enhancements for SharePoint Framework (SPFx) projects.

It simplifies SPFx setup by:

• Configuring Heft webpack patches to inject environment config logic
• Adding reusable scripts
• Creating .env.dev and .env.prod and .env files
• Modifying package-solution.json into a template form
• Updating package.json with necessary scripts and devDependencies

📦 Installation

Install globally via NPM:

npm install -g @opensource365/spfx-env

🚀 Usage

⚠️ Important: Before using spfx-env, make sure to commit (or stash) all your local changes.
The setup process modifies key project files, and having a clean working tree helps avoid merge conflicts or overwrites.

Run in the root directory of your SPFx project:

spfx-env
spfx-env --dry-run

This will apply all enhancements in one go using a command pipeline. Use --dry-run to preview planned changes without modifying files or installing dependencies.

🧪 Development Serve npm run serve

Usage:

npm run serve
npm run serve -- dev
npm run serve -- prod

• Launches heft start for the given environment.
• Internally sets SPFX_ENV to your provided value.
• npm run serve will run on dev environment

🚧 Pack for single environment

Usage:

npm run pack
npm run pack -- dev
npm run pack -- prod

What It Does:

1. Sets SPFX_ENV (by default dev)
2. Runs the full pack process
3. Use process.env.SPFX_ENV in your SPFx code for the selected environment name

🚀 Pack for all environments

Usage:

npm run pack:all

What It Does:

1. Executes your custom scripts/pack-all.js, which:
   • Iterates over all available environments (env/.env.{SPFX_ENV})
   • Sets SPFX_ENV accordingly for each environment
   • Builds and packages the SPFx solution for each environment
   • Packages will be stored in sharepoint/solution/{SPFX_ENV}

🧰 Core Build Script npm run pack:core

• Performs the full SPFx packaging pipeline for the current SPFX_ENV.
• Assumes you’ve set SPFX_ENV before calling this script.

🔧 Pipeline Overview

When running spfx-env, the following pipeline steps are executed sequentially:

1. Setup Environment Files

• Creates environment-specific files:
  • config/env/.env
  • config/env/.env.dev
  • config/env/.env.prod
• Both files are based on a .env template located in src/templates.
• The base .env file acts as the base for all environments. Values defined in .env.dev or .env.prod override the base variables as needed.
• Existing env files are preserved and are not overwritten.

2. Setup Scripts

• Copies custom build scripts from src/templates/scripts into the root scripts/ directory.

3. Configure Build Pipeline

• Creates config/webpack-patch.json and scripts/spfx-env-webpack-patch.js.
• Preserves existing patchFiles entries and appends the spfx-env patch only once.
• Upgrades older config/webpack-patch/* patch locations to scripts/spfx-env-webpack-patch.js if needed.

4. Patch package.json

• Adds or updates essential scripts:
  • pack:core
  • pack
  • serve
  • pack:all
• Installs necessary devDependencies:
  • dotenv
  • dotenv-webpack
  • @types/webpack-env

5. Patch package-solution.json

• Renames package-solution.json to package-solution.tpl.json.
• Enables use of environment variables inside the template:

  {
    "solution": {
      "path": "solution/$SPFX_ENV$/<your-package>.sppkg"
    }
  }

• Supports $ENV_VARIABLE_NAME$ placeholders.

6. Install Dependencies

• Installs all newly added dependencies and scripts.

🧪 Development

To test locally:

npm run build
npm link

Then, in any SPFx project:

spfx-env

💡 Notes

• Custom .env templates should be placed in src/templates/.env.
• Assumes package-solution.json is located in config/.
• Generated Heft integration lives in config/webpack-patch.json and scripts/spfx-env-webpack-patch.js.

📄 License

MIT © OpenSource365