@microsoft/spfx-web-build-rig unnecessarily generates lib-commonjs folder in SPFx projects

[StfBauer]

Environment

• Target SharePoint environment: SharePoint Online
• Development model: SharePoint Framework (SPFx 1.22.2)
• Developer environment: macOS
• Node.js: v22.14.0
• Rig package: @microsoft/spfx-web-build-rig 1.22.2

Describe the bug / error

The default rig package @microsoft/spfx-web-build-rig (v1.22.2) generates a lib-commonjs folder during the build of SPFx web part projects. Since SPFx projects are bundled by webpack for browser delivery, the CommonJS module output is never consumed and serves no purpose.

Three configurations in the rig cause this:

1. additionalModuleKindsToEmit in the rig's config/typescript.json instructs the Heft TypeScript plugin to emit a second CommonJS build into lib-commonjs, in addition to the primary ESNext output in lib/.

2. The copy-javascript task in the rig's config/heft.json copies .js source files from src/ to both ./lib and ./lib-commonjs.

3. cssOutputFolders in the rig's config/sass.json emits compiled CSS to both ["lib", "lib-commonjs"].

The lib-commonjs output is not referenced anywhere in the SPFx webpack pipeline — only the lib/ folder (ESNext modules) is consumed by webpack. This results in unnecessary build time and disk usage for every SPFx project.

Workaround

Projects can override the rig configuration at the project level. Note that Heft's config extends uses append as the default array merge strategy, so setting an array to [] does not override the parent — you must use null to delete inherited array values.

1. Set "additionalModuleKindsToEmit": null in config/typescript.json to delete the inherited CommonJS emit
2. Create a project-level config/heft.json (full copy from the rig) and change the copy-javascript task's destinationFolders from ["./lib", "./lib-commonjs"] to ["./lib"]
3. Replace config/sass.json with a standalone config (no extends) that sets "cssOutputFolders": ["lib"]

Steps to reproduce

1. Scaffold a new SPFx 1.22.2 project using yo @microsoft/sharepoint
2. Run npx heft build --clean
3. Observe that both lib/ and lib-commonjs/ folders are created in the project root

Expected behavior

Only the lib/ folder (ESNext modules) should be generated, as this is the only output consumed by the webpack bundling step. The lib-commonjs folder should not be created for SPFx web part projects.

[Ashlesha-MSFT]

@StfBauer,
Thank you for bringing this issue to our attention.
As noted in the RC discussion thread.:
“The lib-commonjs exists as a target for jest tests.”

That helps clarify that the lib-commonjs output in SPFx 1.22 is intentional.

I’ll tag the engineering team internally for confirmation on whether there are any future plans to make the CommonJS emit optional, or if the dual output is expected to remain part of the default rig design.

[juliemturner]

@Ashlesha-MSFT - From what I can tell the only reference to jest is the typing's for heft-jest. I would much prefer to see this be not on by default with some documentation about how to enable jest testing if you so desire to use jest... which I suspect if you had metrics is probably <.01% of SPFx solutions. Especially since there are other options out there.

[StfBauer]

@Ashlesha-MSFT Thank you for the context that lib-commonjs serves as a Jest target. I want to push back on this architecture respectfully:

1. The scaffolded project has zero test files.
   Every SPFx developer pays for dual compilation on every build for a testing feature that isn't even scaffolded.

2. lib-commonjs is generated during heft build, not heft test.
   If it's only for Jest, it should be produced during the test phase, not on every build, serve, or package operation.

3. No other major framework does this.
   Next.js, Vite, Angular, and Remix all handle Jest + ESM via test-time transforms (ts-jest, @swc/jest, babel-jest) rather than pre-compiling the entire project twice. This is a solved problem.

4. The cited ESM concern is outdated.
   The jest-web.config.json comment mentions --experimental-vm-modules, but a Jest transform converts ESM to CommonJS before execution, so native ESM support isn't even needed.

5. Opting out requires overriding three config files
   (typescript.json, heft.json, sass.json), One of which must be fully duplicated. Additionally, Heft's extends appends arrays by default, so [] doesn't actually override, and you have to use null instead. This also blocks developers who want to bring their own Jest configuration independent of the Heft build chain, since the rig assumes control of Jest's module resolution strategy.
   The fact that three files need to be updated makes it impossible to opt out with the common tools we have at hand for the Heft build chain, e.g., Heft patches.

6. It couples the build to Jest.
   Jest is no longer the clear industry default. Vitest is rapidly gaining ground (~20M weekly npm downloads vs. Jest's ~30M) and is the preferred choice for new projects across the ecosystem. Both work equally well with tools like Puppeteer or Playwright for E2E testing. Organisations and SPFx developers should be able to choose their own test framework without the build chain prescribing one. A Jest-specific workaround shouldn't be baked into every SPFx build.

7. Microsoft's own docs don't use lib-commonjs for testing.
   The only official documentation on testing SPFx web parts (CI/CD with Azure DevOps) runs Jest as a standalone npm script with a community preset (@voitanos/jest-preset-spfx-react16), pointing rootDir at src/ and completely bypassing Heft's Jest integration. It doesn't reference lib-commonjs anywhere. So the architecture being defended here isn't even used in Microsoft's own recommended testing approach. According to the documentation, it also seems Microsoft hasn’t implemented Jest for testing, and the official Microsoft recommendation is to use the community tool without explicitly stating so.

8. Performance and disk impact scale with project size.
   On a minimal scaffolded project, lib-commonjs already adds 80KB and 11 duplicated files. In real-world SPFx solutions with dozens of web parts and components, this doubles the size of every compiled .js, .js.map, .d.ts, .css, and static asset. In CI/CD pipelines, this means longer build times and increased disk I/O on every change, all for output that webpack never touches.

Suggestions:

• The dual emit should be opt-in, or moved to the test phase, so heft build only produces lib/.
• If Jest support is important, provide documentation on how to set up Jest testing properly (e.g., with a test-time transform) instead of baking it into the build output. This would also allow the community to define how testing should work optimally for their projects, whether through the build rig or a dedicated native npm script using Jest.

[VesaJuvonen]

thx @StfBauer on initiating the discussion here. Our engineering team is looking into this now more closely and we'll come back with a conclusion and our planned actions within upcoming days. Some of the reported topics are by design or historical decisions which were done at the time - but we are now looking into revisiting those decision to ensure that there is clear messaging on the reasoning on the decisions and we'll also revisit the need of any further documentation or updates on our guidance or default project structure. Give us few days for coming back to this.