npm package: @opensource365/spfx-env
Description: Add environments for your SPFx solution
Author: OpenSource365
Latest version: 2.0.0

# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:
  ```json
  {
    "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:

```bash
npm run build
npm link
```

Then, in any SPFx project:

```bash
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](https://opensource365.org)