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:

• Patching gulpfile.js 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

This will apply all enhancements in one go using a command pipeline.

🧪 Development Serve npm run serve

Usage:

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

• Launches fast-serve or gulp serve for the given environment.
• Internally sets NODE_ENV to your provided value.
• Controlled via scripts/serve.js.
• 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 NODE_ENV (by default dev)
2. Runs the full pack process

🚀 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.{NODE_ENV})
   • Sets NODE_ENV accordingly for each environment
   • Builds and packages the SPFx solution for each environment
   • Packages will be stored in sharepoint/solution/{NODE_ENV}

🧰 Core Build Script npm run pack:core

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

🔧 Pipeline Overview

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

1. Detect Fast-Serve

• Detects whether the current SPFx project uses Fast-Serve.

2. 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.

3. Setup Scripts

• Copies custom build scripts from src/templates/scripts into the root scripts/ directory.
• Additional script adjustments are made based on Fast-Serve detection.

4. Patch Gulpfile.js

• Inserts gulpCreatePackageSolution() and gulpDeletePackageSolution().
• Injects webpack.gulpSetupEnv() into build.configureWebpack.mergeConfig(...).
• Ensures insertion before build.initialize(require('gulp')).

5. Patch package.json

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

6. Patch package-solution.json

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

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

• Supports $ENV_VARIABLE_NAME$ placeholders.

7. Fast-Serve (optional)

If Fast-Serve is detected:

• Ensures Fast-Serve configuration is extended.
• Injects environment setup logic into fast-serve/webpack.extend.js.

8. 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/.

📄 License

MIT © OpenSource365