Allow Extensions to use `.force_overrides` @@W-18216861@@ by bendvc · Pull Request #2380 · SalesforceCommerceCloud/pwa-kit

bendvc · 2025-04-29T17:13:32Z

Description

As we make the transition from our current version of extensibility (v3) to the next version (v4) we believe that customers will want to retain many of their overrides that we currently have. This lead to the birth of the .force_overrides file which allows you to overrides an extensions public file API and provide overrides for any file that exists in an extension. Allowing the customer to unwind their level of overrides to zero if possible to get them to a place where upgradability isn't a challenge.

Currently this feature only works in the base project (aka the project that you generate) but not in an extension project. This has been identified as a short coming of our API via one of our feedback sessions where a users voiced that they might want to override more than the public API if required. This could be for scenarios where they don't want to wait for use to make changes to our extensions to support features or customizations they want.

In this PR I enable the .force_overrides for application extension projects.

Types of Changes

Bug fix (non-breaking change that fixes an issue)
New feature (non-breaking change that adds functionality)
Documentation update
Breaking change (could cause existing functionality to not work as expected)
Other changes (non-breaking changes that does not fit any of the above)

Changes

OverridesResolverLoader uses a combined list of all "force_override" file paths in the base project and the extensions.

How to Test-Drive This PR

I have left in the template-typescript-minimal project configured with the store locator and the starter extensions. The starter extension has been updated to have a force_overrides file and an override to the store locator that isn't normally overridable.

In the template-typescript-minimal project run npm run start
Once the application is up and running, verify that the override added to the starter extension works. You can do this by going to the /store-locator path.
You should see a page that have a store locator content component that simply says hello

Checklists

General

Changes are covered by test cases
CHANGELOG.md updated with a short description of changes (not required for documentation updates)

TODO

Revert changes to typescript minimal configuration.

cc-prodsec · 2025-04-29T17:36:54Z

🎉 Snyk checks have passed. No issues have been found so far.

✅ security/snyk check is complete. No issues have been found. (View Details)

✅ license/snyk check is complete. No issues have been found. (View Details)

vmarta

I've test-driven the PR and could see the app extension doing a force override successfully as described.

vmarta · 2025-05-02T18:42:17Z

packages/pwa-kit-extension-sdk/src/configs/webpack/overrides-resolver-loader.ts

    // Lets use the compiler configuration to ensure we are resolving the correct file extensions.
-    const compilerOptions = this._compiler?.options
-    const extensions = compilerOptions?.resolve?.extensions || []
+    const extensions = options?.resolveExtensions


Minor: this is where the webpack world and our app extensions collide :) Maybe rename this extensions to fileExtensions to differentiate it from app extensions?

vmarta · 2025-05-02T19:19:22Z

packages/pwa-kit-extension-sdk/src/configs/utils.ts

 }
+
+/**
+ * PRIVATE: Reads and parses a .force_overrides file into a list of clean override entries.


Minor: jsdoc has @private that we can use here.

adamraya · 2025-05-02T22:01:41Z

packages/pwa-kit-extension-sdk/src/configs/webpack/overrides-resolver-loader.ts

-    const projectPath = resourcePath.split(SRC)[0]
+    const projectRelPath = resourcePath.split(`${SRC_FOLDER}${path.sep}`)[1].split('.')[0] // File path relative to the project directory without file extension
+    const projectPath = resourcePath.split(SRC_FOLDER)[0]
    const options = this.getOptions()


Should we print a warning for visibility when we detect the .force_overrides is being used with a similar copy?

pwa-kit/packages/extension-starter/.force_overrides

Lines 3 to 5 in 7d38fc4

// BY USING THIS FILE, YOU AGREE THAT THE FUNCTIONALITY OF YOUR INSTALLED EXTENSION(S) IS NOT GUARANTEED.

// ADDITIONALLY UPGRADABILITY OF EXTENSIONS CAN ALSO NO LONGER BE GUARANTEED AND IS NOT SUPPORTED BY SALESFORCE.

// USE ONLY AS A TEMPORARY SOLUTION TO URGENTLY PATCH/UPDATE AN EXTENSION.

Force overrides are in use. This may impact the upgradeability of extensions. Use only as a temporary solution for urgent fixes.

We could print the warning based on the overridablesSet:

if (overridablesSet.size > 0) { showWarning() }

We decided for now not to do this as we are unsure of the path forward on force_overrides.

adamraya · 2025-05-02T22:14:57Z

packages/extension-starter/.force_overrides

Do we want to update the script npm run list-overrides to list the unused file override defined in the extensions .force-overrides?

Turns out that this script doesn't use the force-overrides directly. So we are going to create a new ticket for this once we get a better idea on the scope of the requirements.

Ticket is created here --> https://gus.lightning.force.com/lightning/r/ADM_Work__c/a07EE00002Dzrf2YAB/view

adamraya · 2025-05-02T23:16:19Z

packages/pwa-kit-extension-sdk/src/configs/utils.ts

+        return content
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line && !line.startsWith('//'))
+            .map((line) => line.split('//')[0].trim()) // remove inline comments
+            .filter(Boolean)


The .filter(Boolean) at the end looks like is redundant

If there is a line with only a comment on it, this filter ensures that the empty line isn't included.

adamraya · 2025-05-02T23:23:18Z

packages/pwa-kit-extension-sdk/src/configs/utils.ts

+    return [
+        path.join(projectDir, OVERRIDABLE_FILE_NAME),
+        ...extensions
+            .map((ext) => {


nit: we can use flatMap() instead of .map() ... .flat()

…ion-force-overrides

adamraya · 2025-05-06T17:21:07Z

packages/template-typescript-minimal/.force_overrides

 // MULTIPLE OVERRIDES CAN BE ADDED TO THIS FILE, ONE PER LINE.\
 // EXAMPLE:
-// ./node_modules/@salesforce/extension-sample/src/pages/home.tsx
+./node_modules/@salesforce/extension-sample/src/pages/home.tsx


I think you want to revert this change by default.

bendvc added 2 commits April 25, 2025 13:59

Initial implementation

5fd0b2b

Make constants file, clean up, remove logs

a9d038f

bendvc requested a review from a team as a code owner April 29, 2025 17:13

bendvc requested review from adamraya and vmarta April 29, 2025 17:28

bendvc added the skip changelog Skip the "Changelog Check" GitHub Actions step even if the Changelog.md files are not updated label Apr 29, 2025

Update CHANGELOG.md

fb9550e

bendvc added 2 commits April 29, 2025 10:48

Add tests for utilities.

f48a14b

Fix failing tests

7d38fc4

vmarta approved these changes May 2, 2025

View reviewed changes

adamraya reviewed May 2, 2025

View reviewed changes

bendvc added 4 commits May 5, 2025 14:53

PR feedback round 1

64067c4

Merge branch 'feature/extensibility-v2' into bendvc/W-18216861_extens…

56a7b32

…ion-force-overrides

Remove test configuration

a02fbf6

Remove sample override for testing

19dd0c9

adamraya reviewed May 6, 2025

View reviewed changes

adamraya approved these changes May 6, 2025

View reviewed changes

Revert override

e6b2789

bendvc merged commit 83c0a71 into feature/extensibility-v2 May 6, 2025
33 checks passed

bendvc deleted the bendvc/W-18216861_extension-force-overrides branch July 16, 2025 22:17

	// BY USING THIS FILE, YOU AGREE THAT THE FUNCTIONALITY OF YOUR INSTALLED EXTENSION(S) IS NOT GUARANTEED.
	// ADDITIONALLY UPGRADABILITY OF EXTENSIONS CAN ALSO NO LONGER BE GUARANTEED AND IS NOT SUPPORTED BY SALESFORCE.
	// USE ONLY AS A TEMPORARY SOLUTION TO URGENTLY PATCH/UPDATE AN EXTENSION.

Conversation

bendvc commented Apr 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Types of Changes

Changes

How to Test-Drive This PR

Checklists

General

TODO

Uh oh!

cc-prodsec commented Apr 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎉 Snyk checks have passed. No issues have been found so far.

Uh oh!

vmarta left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamraya May 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamraya May 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bendvc commented Apr 29, 2025 •

edited

Loading

cc-prodsec commented Apr 29, 2025 •

edited

Loading

adamraya May 2, 2025 •

edited

Loading

adamraya May 2, 2025 •

edited

Loading