SPFx 1.22.0-beta.4 - Community Feedback

[nick-pape]

Please use this post as an aggregated discussion place for ideas and feedback that don't necessarily warrant an Issue ticket.

Prior feedback posts:

• 1.22.0-beta.3

[stevebeauge]

Hi,

It's unclear how to customize webpack in the new toolchain.

The page SharePoint Framework Toolchain: Rush Stack, Heft, & Webpack mention, as far as I understand, that we should customize webpack through the heft configuration files.

The heft webpack plugin suggest we can create a root webpack.config.js file. But it doesn't work, the file does not seems to be called at all. Also tried inside config folder.

A simple sample would be appreciated. Like the old toolchain explained how to add some custom loaders.

Thanks

[nick-pape]

Documentation on this will be released as part of the RC or GA of 1.22 along with migration samples. But for now, here's some instructions for customizing webpack, and for injecting additional tasks (two common scenarios for gulpfile.js). Note this is not official documentation, it is specific to the beta and is subject to change:

---

Migrate gulpfile.js

The most complex part of this process will be migrating your gulpfile.js. This file is ignored by Heft and has no effect.
Once you've migrated, you can simply delete it.

Does not require migration:

• The SASS build suppression does not require migration.
• The renaming of the serve-deprecated task to serve does not require migration. (Note: the equivalent heft command is heft start).
• build.initialize(...) does not require migration.

Webpack modification

webpack-patch-plugin

SPFx-with-Heft includes a simple upgrade path for custom webpack modifications.

Anywhere where you are modifying the webpack config via:

build.configureWebpack.mergeConfig({
  additionalConfiguration: (generatedConfig) => {
    /* modify the webpack config here */
  }
});

Can now be migrated to a "webpack patch" file. These are composable reusable snippets.

1. Create a patch-webpack.mjs (or patch-webpack.js for CommonJS) with the following:

export default function(webpackConfig) {

   /* modify the webpack config here */

    return webpackConfig;
}

Note: you can use either ESM or CommonJS syntax. If using CommonJS, you may need to turn off linter rules. It may be easiest to use ESM.
Note: the file should have a default export that is a function accepting the generated webpack config.
It's fine to modify the webpack object in-place, but the function must return a webpack config object.

2. Create a config/webpack-patch.json file with:

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/spfx-build/webpack-patch.schema.json",
  "patchFiles": [
    "patch-webpack.js"
  ]
}

The "patch-webpack.js" is the name of the patch. You can include multiple patches, they are applied in-order. The path is
resolved relative to the project root.

Migrating custom gulp tasks

If your gulpfile.js contains custom gulp tasks (beyond webpack configuration), you'll need to migrate them to Heft custom tasks.

Using the run-script-plugin

The most straightforward way to migrate custom gulp tasks is to use Heft's run-script-plugin from @rushstack/heft.

Example: Migrating a ` task

1. Extract the gulp task logic to a standalone Node.js script:

Create scripts/custom-task.js:

/* eslint-env node */
/* eslint-disable @typescript-eslint/no-var-requires, @typescript-eslint/no-require-imports */

const path = require('path');
const fs = require('fs');


// IMPORTANT: The run-script-plugin requires a runAsync export
function runAsync( options ) {
  // ... your task logic here ...

  // tap promises to do async things with:
  options.heftTaskSession.hooks.run.tapPromise('my-custom-task', async () => {
    // ... put async code here ...
  });
}

module.exports = { runAsync };

Important: The run-script-plugin requires your script to export a runAsync function. This function should be async and perform your task logic.

Docs: for script-based Heft configs are here: https://heft.rushstack.io/pages/plugins/run-script/

2. Create a custom config/heft.json to extend the rig and add your task:

{
  "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json",

  "extends": "@microsoft/spfx-web-build-rig/profiles/default/config/heft.json",

  "phasesByName": {
    "my-custom-command": { // <-- the heft command, i.e. "heft custom-command"
      "tasksByName": {
        "my-custom-task": {  // <-- the name of the task, as it appears in logs, etc
          "taskDependencies": [], // <-- a list of other tasks that need to be run first
          "taskPlugin": {
            "pluginPackage": "@rushstack/heft",
            "pluginName": "run-script-plugin",
            "options": {
              "scriptPath": "scripts/my-custom-task.js" // <-- the js file with runAsync export
            }
          }
        }
      }
    }
  }
}

3. Add script entries to package.json:

{
  "scripts": {
    "my-custom-command": "heft my-custom-command",
    "build:ci": "heft build --production && heft package-solution --production && heft run --only package-sourcemaps --"
  }
}

4. You can now run command with npm run my-custom-command (or heft my-custom-command)

Heft plugin

For more common or repeated scenarios, look at creating a Heft plugin. (Docs coming soon)