Commit 9960c77e614 for woocommerce
commit 9960c77e6148481847cdb5754f6429b8a48a9a7a
Author: Raluca Stan <ralucastn@gmail.com>
Date: Mon Sep 14 12:53:04 2026 +0200
Document that @woocommerce/settings is an alias for wc.wcSettings (#68615)
* Document that @woocommerce/settings is an alias for wc.wcSettings
* Add changelog entries for the @woocommerce/settings docs update
* Document that wc-store-data and wc-csv are registered in wp-admin only
* Document the wc-settings footer requirement and name the wc.wcSettings module
* Add getAdminLink to the Jest mock recipe for @woocommerce/settings
diff --git a/docs/block-development/reference/integration-interface.md b/docs/block-development/reference/integration-interface.md
index e3d1f768ea5..c81424a6630 100644
--- a/docs/block-development/reference/integration-interface.md
+++ b/docs/block-development/reference/integration-interface.md
@@ -193,6 +193,14 @@ Now, when we load a page containing either block, we should see the scripts we r
We associated some data with the extension in the `get_script_data` method of our interface, we need to know how to get this!
-In the `@woocommerce/settings` package there is a method you can import called `getSetting`. This method accepts a string. The name of the setting containing the data added in `get_script_data` is the name of your integration (i.e. the value returned by `get_name`) suffixed with `_data`. In our example it would be: `woocommerce-example-plugin_data`.
+On the client, read it with `getSetting` from the `wc.wcSettings` global, which the `wc-settings` script provides. Make sure your script lists `wc-settings` as a dependency and loads in the footer, as the example above does with the last `wp_register_script` argument; WooCommerce moves header scripts that depend on `wc-settings` to the footer and logs a console warning. The name of the setting containing the data added in `get_script_data` is the name of your integration (i.e. the value returned by `get_name`) suffixed with `_data`. In our example it would be: `woocommerce-example-plugin_data`.
-The value returned here is a plain old JavaScript object, keyed by the keys of the array returned by `get_script_data`, the values will serialized.
+```js
+const { getSetting } = window.wc.wcSettings;
+
+const data = getSetting( 'woocommerce-example-plugin_data', {} );
+```
+
+If you build with [`@woocommerce/dependency-extraction-webpack-plugin`](https://github.com/woocommerce/woocommerce/tree/trunk/packages/js/dependency-extraction-webpack-plugin), you can write `import { getSetting } from '@woocommerce/settings';` instead. The build maps that import to the same global and adds `wc-settings` to your script dependencies for you. `@woocommerce/settings` is an alias handled by the build, not the npm package of that name, which is deprecated.
+
+The value returned here is a plain old JavaScript object, keyed by the keys of the array returned by `get_script_data`, the values will be serialized.
diff --git a/packages/js/components/README.md b/packages/js/components/README.md
index cb6fb053e47..ba25b000daf 100644
--- a/packages/js/components/README.md
+++ b/packages/js/components/README.md
@@ -36,29 +36,7 @@ In non-WordPress projects, link to the `build-style/card/style.css` file directl
If you are using these components in a project that uses Jest for testing, you may get an error that looks like this:
```bash
-Cannot find module '@woocommerce/settings' from 'node_modules/@woocommerce/experimental/node_modules/@woocommerce/navigation/build/index.js'
+Cannot find module '@woocommerce/settings' from 'node_modules/@woocommerce/navigation/build/index.js'
```
-To fix this, you will need to mock the `@woocommerce/settings` because it's an alias that points to the `window.wcSettings`, which in turn comes from and is maintained by the [WC Blocks](https://github.com/woocommerce/woocommerce-blocks) package, the front-end code for this is located [plugins/woocommerce/client/blocks/packages/public-api/settings](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/client/blocks/packages/public-api/settings).
-
-This can be done by adding the following to your Jest config:
-
-```js
-module.exports = {
- moduleNameMapper: {
- '@woocommerce/settings': path.resolve(
- __dirname,
- './mock/woocommerce-settings'
- ),
- }
- setupFiles: [
- path.resolve( __dirname, 'build/setup-globals.js' ),
- ],
- // ...other config
-}
-```
-
-Then, you will need to create the following files:
-
-1. Create a new file called woocommerce-settings.js in the ./mock directory. You can find the content for this file [packages/js/internal-js-tests/src/mocks/woocommerce-settings.js#L1](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/internal-js-tests/src/mocks/woocommerce-settings.js#L1).
-2. Next, create a file named setup-globals.js. You can find the content for this file [packages/js/internal-js-tests/src/setup-globals.js#L44](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/internal-js-tests/src/setup-globals.js#L44). The purpose of this file is to mock the wcSettings global variable.
+`@woocommerce/settings` is an alias for the `wc.wcSettings` module from WooCommerce core, not an npm package, so Jest cannot resolve it. Some dependencies of this package import it. To fix the error, map the alias to a local mock and define the `wcSettings` data global that the module reads in a Jest setup file. See [Using `@woocommerce/settings` with Jest](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/dependency-extraction-webpack-plugin/README.md#using-woocommercesettings-with-jest) in the dependency extraction plugin README for the config and mock to use.
diff --git a/packages/js/components/changelog/wooplug-929-settings-alias-docs b/packages/js/components/changelog/wooplug-929-settings-alias-docs
new file mode 100644
index 00000000000..148896f38a6
--- /dev/null
+++ b/packages/js/components/changelog/wooplug-929-settings-alias-docs
@@ -0,0 +1,3 @@
+Significance: patch
+Type: dev
+Comment: Point the Jest mocking note for @woocommerce/settings to the dependency extraction plugin README.
diff --git a/packages/js/data/README.md b/packages/js/data/README.md
index 16c6f687dd9..bd130eac213 100644
--- a/packages/js/data/README.md
+++ b/packages/js/data/README.md
@@ -2,6 +2,8 @@
WooCommerce Admin data store and utilities.
+WooCommerce registers the `wc-store-data` script in wp-admin only, so these stores are not available on the storefront or in blocks rendered there. For settings in blocks and storefront code, use `getSetting` from `wc.wcSettings` instead. See [`@woocommerce/settings` in the dependency extraction plugin README](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/dependency-extraction-webpack-plugin/README.md#woocommercesettings).
+
## Installation
Install the module
diff --git a/packages/js/data/changelog/wooplug-929-settings-alias-docs b/packages/js/data/changelog/wooplug-929-settings-alias-docs
new file mode 100644
index 00000000000..f5a94fd9ea0
--- /dev/null
+++ b/packages/js/data/changelog/wooplug-929-settings-alias-docs
@@ -0,0 +1,3 @@
+Significance: patch
+Type: dev
+Comment: Note in the README that wc-store-data is registered in wp-admin only.
diff --git a/packages/js/dependency-extraction-webpack-plugin/README.md b/packages/js/dependency-extraction-webpack-plugin/README.md
index 8e7fa4f7745..8e724acc2fc 100644
--- a/packages/js/dependency-extraction-webpack-plugin/README.md
+++ b/packages/js/dependency-extraction-webpack-plugin/README.md
@@ -44,13 +44,60 @@ Additional module requests on top of WordPress [Dependency Extraction Webpack Pl
| Request | Global | Script handle | Notes |
| --- | --- | --- | --- |
-| `@woocommerce/data` | `wc['data']` | `wc-store-data` | |
-| `@woocommerce/csv-export` | `wc['csvExport']` | `wc-csv` | |
+| `@woocommerce/data` | `wc['data']` | `wc-store-data` | Registered in wp-admin only. Not available on the storefront. |
+| `@woocommerce/csv-export` | `wc['csvExport']` | `wc-csv` | Registered in wp-admin only. Not available on the storefront. |
| `@woocommerce/blocks-registry` | `wc['wcBlocksRegistry']` | `wc-blocks-registry` | |
| `@woocommerce/block-data` | `wc['wcBlocksData']` | `wc-blocks-data-store` | This dependency does not have an associated npm package |
-| `@woocommerce/settings` | `wc['wcSettings']` | `wc-settings` | |
+| `@woocommerce/settings` | `wc['wcSettings']` | `wc-settings` | This is an alias for a WooCommerce core script, not the npm package of the same name. See below. |
| `@woocommerce/*` | `wc['*']` | `wc-*` | |
+### `@woocommerce/settings`
+
+The `@woocommerce/settings` request is not the [`@woocommerce/settings` npm package](https://www.npmjs.com/package/@woocommerce/settings). That package is deprecated and should not be installed. The plugin maps the request to the `wc.wcSettings` module and adds `wc-settings` to your script dependencies; WooCommerce core loads that script whenever a script depends on the `wc-settings` handle, and prints the data it reads into the `wcSettings` global right before it. The source lives in [`plugins/woocommerce/client/blocks/packages/public-api/settings`](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/client/blocks/packages/public-api/settings).
+
+Register scripts that depend on `wc-settings` in the footer. The settings data is collected during the request, so a script running in the header would read it before it is complete. WooCommerce moves such scripts to the footer for you and logs a console warning.
+
+Use `getSetting` to read data that WooCommerce, or your own PHP code, registered on the server. See [Data flow: server to client](https://github.com/woocommerce/woocommerce/blob/trunk/docs/block-development/reference/overview-of-data-flow.md#server-php-to-client-javascript) for how to register that data.
+
+```js
+import { getSetting } from '@woocommerce/settings';
+
+const value = getSetting( 'my-plugin/value', 'fallback' );
+```
+
+#### Using `@woocommerce/settings` with Jest
+
+Jest cannot resolve the request because there is no package to install. Map it to a local mock and define the `wcSettings` global in a setup file:
+
+```js
+// jest.config.js
+module.exports = {
+ moduleNameMapper: {
+ '@woocommerce/settings': '<rootDir>/tests/mocks/woocommerce-settings.js',
+ },
+ setupFiles: [ '<rootDir>/tests/setup-globals.js' ],
+};
+```
+
+```js
+// tests/mocks/woocommerce-settings.js
+module.exports = {
+ getSetting: ( name, fallback = false ) =>
+ name in global.wcSettings ? global.wcSettings[ name ] : fallback,
+ getAdminLink: ( path ) =>
+ global.wcSettings.adminUrl ? global.wcSettings.adminUrl + path : path,
+};
+```
+
+```js
+// tests/setup-globals.js
+global.wcSettings = {
+ adminUrl: 'https://example.com/wp-admin/',
+};
+```
+
+Mock the helpers and settings that your code and its dependencies use. For example, `@woocommerce/navigation`, which `@woocommerce/components` depends on, calls `getAdminLink`. The mock and global that the WooCommerce monorepo uses for its own tests are in [`packages/js/internal-js-tests/src/mocks/woocommerce-settings.js`](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/internal-js-tests/src/mocks/woocommerce-settings.js) and [`packages/js/internal-js-tests/src/setup-globals.js`](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/internal-js-tests/src/setup-globals.js).
+
### Options
An object can be passed to the constructor to customize the behavior, for example:
diff --git a/packages/js/dependency-extraction-webpack-plugin/changelog/wooplug-929-settings-alias-docs b/packages/js/dependency-extraction-webpack-plugin/changelog/wooplug-929-settings-alias-docs
new file mode 100644
index 00000000000..f3e06f2872c
--- /dev/null
+++ b/packages/js/dependency-extraction-webpack-plugin/changelog/wooplug-929-settings-alias-docs
@@ -0,0 +1,3 @@
+Significance: patch
+Type: dev
+Comment: Document that @woocommerce/settings is an alias for wc.wcSettings, not the deprecated npm package, and how to mock it in Jest.