SPFx 1.22.0-rc.0 - 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.

Changes in the RC

• We bring back the lib-commonjs build output, and switch the lib/ back to ESM (to support webpack chunking). The lib-commonjs exists as a target for jest tests.
• Fixes an issue where typescript version is overwritten during eject.
• Fixes incorrect @rushstack/heft peer dependency issue.

Other notes

• We are aware that ESLint 8 is deprecated. We've upgraded our internal repository to use ESLint 9. SPFx 1.23 with Heft will include the ESLint 9 upgrade; however, the current plan is that the Gulp-based toolchain will remain on ESLint 8.
• SASS Sourcemaps are not currently supported by Heft SASS plugin at this time. We will work to get this added to Heft, and it will be included in 1.23 release.

Prior feedback posts:

• 1.22.0-beta.5
• 1.22.0-beta.4
• 1.22.0-beta.3

[andrewconnell]

TL;DR: Move eslint config ▶ spfx-web-build-rig

Since we now have a build configuration refactored into a rig, with its own configurations for things like:

• ./tsconfig.json extending ▶ *./node_modules/@microsoft/spfx-web-build-rig/profiles/default/tsconfig-base.json
• ./config/sass.json extending ▶ @microsoft/spfx-web-build-rig/profiles/default/config/sass.json**
• ./config/typescript.json extending ▶ @microsoft/spfx-web-build-rig/profiles/default/config/typescript.json

... how about new SPFx projects use the same approach for ./.eslintrc.js?

proposal ▶ move ESLint config to SPFx rig

1. copy ./.eslintrc.js ▶ *./node_modules/@microsoft/spfx-web-build-rig/profiles/default/.eslintrc.js

   not very important, but it could go in the config subfolder with other heft plugin configurations...

2. update existing ./.eslintrc.js config to extend from rig's config so it only contains:

   require('@rushstack/eslint-config/patch/modern-module-resolution');
   module.exports = {
     extends: [./node_modules/@microsoft/spfx-web-build-rig/profiles/default/.eslintrc.js],
     parserOptions: { tsconfigRootDir: __dirname }
   };

benefits

• future updates to the rig package update the ESLint rules without requiring someone to update the actual rules in their existing projects
• customers can apply their own overrides array property to the existing rules...
• ... and future rig updates won't impact their overrides

Inspired by my original article: How to set up reusable ESLint configs for SharePoint Framework (SPFx) projects

[StfBauer]

For regular dev builds. I would love to turn it off when not needed.

[andrewconnell]

Totally agree, but...

You can do that today, but it would be preferred if we had an option to disable it. This isn't as likely to happen because SPFx's rig is using the OOTB Heft Lint plugin, which is used more broadly than just in SPFx solutions.

The alternative to that is what we can do today, both are not trivial...

Option 1 (less work)

1. create ./config/heft.json in your project
2. copy the build phase from the OOTB SPFx rig's profile => your heft.json file
3. remove the lint task from the build phase in your heft.json
4. remove the all references to the lint task in the taskDependencies array in other tasks within the build phase

Downsides:

• somewhat big change to add to EACH project, although once you've done this, you can copy/paste the heft.json file into other projects
• not conditional for dev builds

Option 2 (more work, more control)

1. create a custom heft plugin that extends the OOTB lint plugin
2. modify your plugin to have the settings & requirements you prefer
3. create ./config/heft.json in your project
4. replace just the lint task in the build phase, similar to how I show adding a new task to the build phase in this article, but you just use the same phase & task name to "overwrite" the existing lint task in the SPFx rig

BTW, WRT option #2...

[StfBauer]

And there is another thing missing - You can lint an SPFx way, just the usual way.

"scripts": {
  //...
  "lint": "eslint ./src --ext .ts,.tsx"
}

Low-hanging fruit 🍓, but a common npm script in many modern projects.

[HolgerWurbs]

I noticed hot update not working because webpack serve tries to connect to port 8080. There's also some error spam about it in the console. I could fix it by adding a spfx-customize-webpack.js to the config folder with the following content:

module.exports = function (webpackConfiguration) {
  if (webpackConfiguration.devServer) {
    webpackConfiguration.devServer.client = {
      webSocketURL: {        
        hostname: webpackConfiguration.devServer.host || 'localhost',
        port: webpackConfiguration.devServer.port,
        protocol: 'wss'
      }
    };
  }
  return webpackConfiguration;
};

[nick-pape]

Thanks for reporting this. We will include the fix in the next release.

[thechriskent]

The default README should have it's Microsoft 365 tenant link updated to not include the language code.

It's currently:

- [Microsoft 365 tenant](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/set-up-your-developer-tenant)

It'd be better if it were:

- [Microsoft 365 tenant](https://docs.microsoft.com/sharepoint/dev/spfx/set-up-your-developer-tenant)

Ideally, it would be an aka.ms link pointed at https://learn.microsoft.com/sharepoint/dev/spfx/set-up-your-developer-tenant

[nick-pape]

Thanks for reporting this. These links will be updated in the next release.

[thechriskent]

When running npm run start the first time, I was given a helpful warning about the dev certificate. But the experience of it immediately opening a separate terminal and prompting me for admin credentials and then my password for a sudo command was quite jarring.

I think instead of automatically running the trust-dev-cert stuff, the user should be told about the issue and either told to run the command as part of a failure message or even better be asked if they want to install/update the dev-cert. It's a small thing, but I think you'll end up with less concerned developers - especially since this will be part of a first run experience.

[StfBauer]

Same here, yes, definitely. Although the old cert still works.

[thechriskent]

Creating a production package is going to trip up devs.

We've placed the gulp equivalencies in the 2nd article under the Heft-based toolchain set of docs. In there, we call out that --ship has been replaced with --production:

https://learn.microsoft.com/en-us/sharepoint/dev/spfx/toolchain/customize-heft-toolchain-overview#heft-actions-and-legacy-gulp-tasks

Lame that we changed it from 'ship' to 'production', but I'm guessing that's a heft thing and just how it is. But how it is added to the command has changed since we're now using npm scripts rather than gulp tasks. I think most devs will try and do this:

npm run package-solution --production

Which will be very confusing to them when it looks like this:

The documentation should be updated to point out that the command is actually:

npm run package-solution -- --production

Additionally, I think adding an additional script would make things even easier:

It's less to type, it's easy to find, and easier to understand.

[andrewconnell]

You don't have to use the NPM scripts.

@thechriskent said:

The documentation should be updated to point out that the command is actually:

npm run package-solution -- --production

That -- is only applicable if you're using NPM scripts. The warning you're seeing is coming from Heft, not from anything specific to SPFx... so that's not something SPFx can address.

This is a slippery slope because, taken to its logical conclusion, you'd have to create an NPM script for every argument combination (see build-watch). And when you want to see what commands are available to you, the following won't match the npm script name:

heft --help

Because the above will only list package-solution & pacakge-solution-watch. Also, the normal CLI commands start to get useless for baked in docs, like heft pacakge-solution -h to see all the arguments.

Personally, I prefer to install Heft globally and run the commands just like you do with the gulp-cli in pre-v1.22, as I explain here: Understanding the Heft-based toolchain (how it works): Heft architectural concepts

BTW, there's an error in the docs talking about how ot install heft globally... doc fix in process... PR pending #10499. Short story: because heft is a scoped package, you need the whole name: @rushstack/heft.

[thechriskent]

What is the deploy script? The docs refer to it as dev-deploy and mention that it deploys the assets to a test CDN.

So, what's this command trying to do and how is it different than deploy-azure-storage?

I think we need better guidance on these. Having a script called deploy seems like it would indicate something closer to uploading the packaged solution to an app catalog. This appears to be something dev related, but what that is isn't answered in the docs

[andrewconnell]

dev-deploy is mentioned below this table as a footer.

@thechriskent said:

This appears to be something dev-related, but what that is isn't answered in the docs

Hmmm... I intended to answer that in the footer, but it's not clear enough. I'll take that as an optmization task... but the short story:

The deploy-azure-storage actually deploys your assets (JS bundle, localization file, etc) that you aren't including in the *.sppkg to be provisioned to the ClientSideAssets library. That's used AFTER packaging (ie: heft package-solution --production). IOW, it acts like the same command we had in the gulp-based toolchain.

The dev-deploy is new... it does the following:

1. processes and uploads the SPFx manifests, components & deps
2. gen's a manifest.js file wiht all component metadata
3. creates a debug/test URL for SPO workbench testing

Basically, when you run it, it gets an azure storage container where you want to test your project with your own CDN. it automatically uploads a dynamically gen'd folder (timestamp/hash name) but preserves using the SAS token auth for the container

It then outputs the testing URL with query params, saves the metadata to a local JSON file (dev-deploy-metadata.json

[nick-pape]

Yes, we should document this more clearly.

The scenario for this allowing for testing without having serve running or uploading an sppkg. For example, if you wanted to give a snapshot to a QA team, or if you wanted to setup your CI/CD workflow to provide a persistent test link to reviewers.

[DonKirkham]

I'm probably missing it, but looking at the documentation, the "Set up development environment" page (https://learn.microsoft.com/en-us/sharepoint/dev/spfx/set-up-your-development-environment) has all of the legacy instructions with no mention of Heft. The Heft toolchain section does not talk about setting up the environment either. Is there an "unpublished" update to that page?

[VesaJuvonen]

We are still in Release Candidate side - so the @ current and latest for production is 1.21 with Gulp. This page will be updated as part of the general availability doc updates, but not before that.

Only difference is that you can install Heft globally - so new call to include is npm install -g @rushstack/heft

[andrewconnell]

Not sure how I just noticed this, but was it intentional for v1.22 to drop adding the ./.vsconfig/launch.json VSCode launch config file?

[nick-pape]

No, and we'll get this sorted. It was mentioned here as well: #10442 (comment)

[StfBauer]

When in debug mode, resizing the window and testing for responsive design results in the following error. It must come directly from SharePoint or SPFx, since I don't and won't use ResizeObserver.

[StfBauer]

Sourcemap for Sass is a huge bummer. It finally worked in SPFx, but HEFT ripped it off. 🥲 My personal recommendation is to wait until 1.23.

[StfBauer]

What if I ejected accidentally? Or at some point in the future, I decide not to maintain my own webpack configuration anymore?

How could I inject again? There are many modifications to the files, and there is no clear way to restore the original functionality.

[andrewconnell]

Not possible... it would be 100% manual. As the docs say, if you eject the only way back is to manually undo it... best way to do that: got repo & revert to a cherry picked commit.

FWIW, other products that support ejecting don't support undo'ing that... so this isn't a special SPFx thing.

[andrewconnell]

Also, the doc I published to the SPFx docs about ejecting explains exactly what changed to the project so it's documented.

What's not documented (and IMHO shouldn't be) is how to undo it. After ejecting, your toolchain isn't supported by MSFT.

Kind of like modifying your car: if you void the warranty, you can't undo to get back under warranty.

[sbrown-fc]

I appreciate this might be considered off-topic here, but why in 2025 is the target in the TypeScript config still set to es5?

[sbrown-fc]

Just to add that es5 is being deprecated and in future the lowest target in TS will be es2015.

https://devblogs.microsoft.com/typescript/progress-on-typescript-7-december-2025/

microsoft/TypeScript#62196

[StfBauer]

Naming conventions for NPM scripts should change before launch. I work on many open source projects, and a common pattern is that the scripts don't use hyphens, which gives the npm scripts a clearer structure:

Instead of this:

{
//...
  "scripts": {
    "build": "heft build",
    "test": "heft test",
    "test-only": "heft run --only test --",
    "clean": "heft clean",
    "deploy": "heft dev-deploy",
    "start": "heft start --clean",
    "build-watch": "heft build --lite",
    "package-solution": "heft package-solution",
    "deploy-azure-storage": "heft deploy-azure-storage",
    "eject-webpack": "heft eject-webpack",
    "trust-dev-cert": "heft trust-dev-cert",
    "untrust-dev-cert": "heft untrust-dev-cert",
    "lint": "eslint ./src --ext .ts,.tsx"
  },
  //..
}

The ideal script pattern looks like this:

"scripts": {
  // Build
  "build": "heft build",
  "build:watch": "heft build --lite",

  // Tests
  "test": "heft test",
  "test:only": "heft run --only test --",

  // Cleaning
  "clean": "heft clean",

  // Deployment
  "deploy": "heft dev-deploy",
  "deploy:azure-storage": "heft deploy-azure-storage",

  // Webpack tools
  "webpack:eject": "heft eject-webpack",

  // Dev certificates
  "dev-cert:trust": "heft trust-dev-cert",
  "dev-cert:untrust": "heft untrust-dev-cert",

  // Packaging
  "package:solution": "heft package-solution",

  // Linting
  // Lint all
  "lint": "npm-run-all lint:*",
  // regular liniting
  "lint:ts": "eslint ./src --ext .ts,.tsx",
  "lint:css": "stylelint \"src/**/*.{css,scss}\"",

  // lint and fix
  // fix all
  "lint:fix": "npm-run-all lint:js:fix lint:css:fix",
  // fix individual
  "lint:js:fix": "eslint ./src --ext .ts,.tsx --fix",
  "lint:css:fix": "stylelint \"src/**/*.{css,scss}\" --fix",

  // Start local
  "start": "heft start --clean"
}

Right now, the npm run commands are confusing and not the best practice, from my point of view.
If you use tools like npm-run-all, you can execute the following commands under

# Execute all lint commands
npm-run-all lint:*

or like so:

# Execute all lint commands
npm run lint:fix

Just a small change, but pretty common in the NodeJS development world.

Also, since hyphens and double hyphens are used for command-line options, you have a clear distinction.

[nick-pape]

Related: #10442 (comment)

We will take a look at this. Internally, we are using colons for subtasks as well. We followed the same pattern the gulp toolchain was using, but will revisit this.

[andrewconnell]

I've been sitting on the topic of the npm scripts as the GA was so close, but now that it looks like GA timing will slip to next week, I'd like to propose an alternative consideration...

👉 Please consider removing ALL npm scripts that just call heft

In the gulp-toolchain, we had limited npm scripts... but with heft, for reasons unclear to me, there are a lot more. This has already caused some confusion with some experienced SPFx devs, as seen in this & other pre-GA tracking discussions.

A challenge with npm scripts is that the arguments used when calling an npm script aren't passed in... you have to pipe them in (ie: npm run package-solution -- --production).

IMHO, npm scripts are useful when you want to create an alias or have multiple things you want to do or use it like a macro, but when the following is essentially the same thing:

npm run package-solution
# or
heft package-solution

... this 👆 is, IMHO, unnecessary. If the default project goes this far, why aren't we including a LOT more npm scripts like all the options @StfBauer has above. But... I still think most of those are unnecessary... running npm run clean is not better than heft clean.

This also pushes people to learn scripts rather than the heft commands and syntax. The latter is more flexible, direct access to the arguments, and more.

Further, this isn't an SPFx or Heft issue they're addressing... this is just pure node project, node-based CLI's, and npm scripts... standard stuff.

IMHO, I'd like to see:

1. ALL npm scripts removed in v1.22 down to just replace what we already had in SPFx v1.21.1.
2. if you want to include helpers like this, let's either/both put them in the docs or in the project README.md
3. if someone wants to add a bunch of their own npm scripts... have at it, in your own project
4. we already recommend developers install Heft globally (npm i @rushstack/heft -g)... and if the saavy devs don't want to do that, they can use npx, although that will require more typing having to scope the package each time

My guidance to SPFx devs will be to NOT use the npm scripts provided, rather learn the correct heft commands.

[nick-pape]

When I was reading this discussion yesterday, I had similar thoughts... Essentially, these npm scripts aren't really fundamental to how the build system works. We include them since they are a somewhat standard way of signaling "these are the commands that need to be run", we included (a very limited set) of them with Gulp, etc.

However, the ergonomics of working with npm scripts aren't great. The CLI options often doesn't play nicely with other tools (depending on how they handle parsing), etc.

Really, the package.json scripts are not meant to be some immutable part of the build system. I'd view these as more "here's a starter, go customize to whatever you want". I'd argue that Heft already has good CLI handling (with --help, customizations, etc), and sticking npm in the middle just adds unnecessary confusion. I think we'd also prefer to have everyone talking about the same commands; i.e. heft build, heft package-solution rather than NPM scripts which might be very different per-project.

My proposal would be to reduce the NPM scripts we pre-populate to only what would reasonably be used by CI (i.e. a single production build, production package solution), and maybe a start/serve. The rest should be documented in a "How to run this project?"-style section in the README. In our documentation we can point out that these are intentionally limited, you are free to add whatever structure you want to the package.json scripts, point out the valid reasons you might want to, etc.

[thechriskent]

First, to Stefan's original point, having these use the standard naming convention of colons is a good idea.

Second, to AC and Nick's points, I disagree on the removal of all NPM scripts. NPM scripts are far more standard than heft and have more tooling support. While I agree that the recommendation to install heft globally makes sense for anyone doing anything non-standard, I think it misses the point of conforming to best (or at least common) practice. It also places more burden on devs to understand the underlying build system - which is largely unnecessary for most use cases.

Most SPFx devs will never use anything but the following commands:

• serve
• clean
• bundle
• package-solution

Having these mapped to npm scripts gives the following key benefits:

• Discoverability: These are easy to find and the starting place most new devs will look
• Tool Support: Many of us use VS Code extensions that highlight the scripts and make them easy to run

Here's a comparison table of npm scripts in SPFx:

Command	SPFx Previous	SPFx 1.22	Notes
build	gulp bundle	heft build --clean
clean	gulp clean	heft clean
test	gulp test	heft test
serve	fast-serve	NA	Only when using spfx-fast-serve
test-only	NA	heft run --only test --	Unclear what this does differently than just test above
deploy	NA	heft dev-deploy	This name is misleading as it isn't doing what devs would expect from a deploy
start	NA	heft start --clean
build-watch	NA	heft build --lite	Confusing because heft has its own build-watch and this isn't using it, --lite is also not documented in heft build -h
package-solution	NA	heft package-solution
deploy-azure-storage	NA	heft deploy-azure-storage
eject-webpack	NA	heft eject-webpack
trust-dev-cert	NA	heft trust-dev-cert
untrust-dev-cert	NA	heft untrust-dev-cert

We had the following gulp tasks most of which were not included in NPM scripts:

• clean
• build
• bundle
• deploy-azure-storage
• package-solution
• test
• serve-deprecated
• trust-dev-cert
• untrust-dev-cert
• test-only
• serve

My recommendation:

  "scripts": {
    "build": "heft build --clean",
    "test": "heft test",
    "clean": "heft clean",
    "start": "heft start --clean",
    "pack": "heft build --clean && heft package-solution --production",
    "pack:local": "heft build --clean && heft package-solution",
  },

• build, clean, and test are there for consistency with earlier versions
• start is a nice shortcut for including --clean and is pretty standard
• pack & pack:local are wrappers for the weirdly separate bundle and package-solution tasks that are typically run together (I understand why they can be run separately, but they typically aren't)
• All the other stuff is advanced scenarios and should just be left in heft. The only exception is possibly trust-dev-cert but this was always a separate command and if the start command is going to detect and suggest it anyway, it doesn't need to be here

This allows us to provide the same type of guidance as before while easing entry for new devs.

I think Nick makes an excellent point: Really, the package.json scripts are not meant to be some immutable part of the build system. I'd view these as more "here's a starter, go customize to whatever you want".

In that vein, IMO, these are a good start that covers 90% of use cases without a bunch of extra noise and lets devs quickly get started with the SPFx stuff rather than having to fumble through build system specifics before they need to.

[andrewconnell]

I guess this is going to be a case of agree to disagree. I fundamentally don't understand how npm run clean is better than heft clean.

@nick-pape said:

Really, the package.json scripts are not meant to be some immutable part of the build system. I'd view these as more "here's a starter, go customize to whatever you want". I'd argue that Heft already has good CLI handling (with --help, customizations, etc), and sticking npm in the middle just adds unnecessary confusion.

100% (my emphasis)

@nick-pape said:

I think we'd also prefer to have everyone talking about the same commands; i.e. heft build, heft package-solution rather than NPM scripts which might be very different per-project.

Preach!!!

@thechriskent said:

Discoverability: These are easy to find and the starting place most new devs will look

While true, the problem with this is that they'll stop at what they see in the package.json file.

In teaching tons of developers, when they see something like this, they think this is the universe of options.

If you don't create npm scripts for every permutation, you need to teach them what you experienced above: you need to learn how to pipe an argument in (--).

Teach a man how to fish...

Instead, if you teach them how to use heft -h, they can see everything the tool can do, and that's based on the tool, not based a snapshot of a package.json.

I get that there are different POV's here... just sharing mine.