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)

[nick-pape]

We are aware of an issue with ListView command sets in this beta release and are investigating.

[nick-pape]

Yes, so the issue here is that serveConfigurations handling was not ported to Heft. So, we were unable to construct the correct debug URL for extensions. That's why they are not seen. In addition, the --config flag is not available. We've worked on a fix for these and it will be included in next release.

[nick-pape]

Some CSS issues were reported in #10466

The first issue we are not likely to fix at present, please use the Heft configurations as-is. Tickets can be directly opened in the Rush Stack repo for suggested changes to default Heft plugins. Note: if there are configurations that are not available in Heft, that were available in gulp-based toolchain, please do comment here or open a ticket, we will fix issues if there is not a direct migration available in Heft.

For the 2nd reported issue, we are aware that module scss files are not being treated as such. This is a configuration issue in the SPFx Heft rig, it will be addresses. Most likely the behavior will be adjusted as follows: in the Gulp toolchain, .module.scss files were specifically treated as module CSS, other .scss files were not. In the Heft toolchain, we will adjust the rig such that .global.scss is treated as global SCSS, other .scss (including .module.scss) will be treated as module scss. This change is a consequence of the file extension filtering mechanism being inverted in Heft. The migration path here should only affect files that you do not want as module css; these will need to be renamed to .global.scss.

For the 3rd reported issue, this should be fixed with proper support for module scss, but we will be sure to validate this scenario.

[StfBauer]

Source Maps for CSS currently do not work in the Browser either.

[nick-pape]

Mac OS users are experiencing infinite rebuilds: #10458

This is actually an issue with the TypeScript watcher and was fixed in TypeScript 5.4.0: microsoft/TypeScript#56403

We resolved this by upgrading typescript to a version >5.4.0. We will adjust the default accordingly in the next release (likely, ~5.8.0, which is the latest version supported by Heft).