Commit 4a303cf190c for woocommerce
commit 4a303cf190cede40a48d2bb1c89ff7f46f5a8608
Author: Vlad Olaru <vlad.olaru@automattic.com>
Date: Fri Oct 23 17:48:23 2026 +0300
Clarify WooCommerce Admin extension example setup (#69677)
* docs(admin): Rewrite extension example docs around working examples
The Admin extension examples README never explained WC_EXT, pointed to
a wrong output directory, and listed add-report and add-task, which
moved to create-woo-extension variants. Two of the three remaining
examples no longer do anything: no code reads the notice filters, and
WooCommerce 11.2 removed the Activity panel Inbox drawer that held the
abbreviated notification slot.
Lead the README with the create-woo-extension scaffold, where the
add-report example now lives. Walk through simple-inbox-note, the one
in-repo example with a visible result on WooCommerce > Home: build,
wp-env override, setup wizard skip, editing and cleanup. Label the
abbreviated notification example as having no effect.
Point the add-task links to the scaffold variant, drop the quick start
for the deleted payment gateway suggestions example while keeping its
suggestion specs filter sentence, and update the admin client CLAUDE.md
notes, whose example command fails without WC_EXT.
Refs #50420
* docs(admin): Remove the unused important-admin-notice example
The example adds callbacks to woocommerce_admin_notices_to_show and
woocommerce_admin_should_hide_notice, but nothing in WooCommerce reads
those filters any more. With it active, its four example notices all
render on the Products list and all stay hidden on WooCommerce Home,
whatever the filters ask for, so it demonstrates nothing and misleads
readers.
The files only lived under docs/examples and WooCommerce never loaded
them, so removing them changes no runtime behavior.
Refs #50420
* chore(changelog): Add Admin example documentation entry
Record the Admin extension example documentation update and the
removal of an unused docs example without a merchant release-note
line. Neither change alters production behavior.
Refs #50420
* docs(admin): Remove obsolete notification example listing
The examples README lists an ineffective notification example that a
separate PR removes. Keeping the listing would require coordinating
the merge order to avoid documenting a nonexistent example.
Remove the listing so the documentation remains accurate regardless
of when the example itself is deleted.
Refs #50420
* docs(admin): Complete the inbox example walkthrough
Contributors need a working example before being directed to a scaffold
whose published dependencies currently fail to install. The cleanup
instructions also left the example in the wp-env plugin list.
Lead with the inbox-note walkthrough, explain its persisted edit cycle,
and document deactivation, configuration removal, and cleanup. Move the
scaffold guidance below it and disclose the installation limitation.
Verified the note, rebuild and reactivation, settings action, and
cleanup through the isolated local wp-env browser workflow.
Refs #50420
* docs(admin): Remove obsolete scaffold installation warning
The published create-woo-extension 2.1.0 release includes the React
resolution and generated-project lint fixes. Fresh report and task
scaffolds now install, build, and pass lint with zero warnings.
Remove the warning about the broken 2.0.1 scaffold so the Admin example
guide reflects the released package.
Refs #50420
* docs(admin): Complete the standalone report walkthrough
The Admin example guide explains the monorepo inbox example, but the
standalone report instructions stop after generating the plugin. Readers
following the original report example need a path to its visible result.
Introduce both workflows at the top and complete the report walkthrough
with prerequisites, WordPress startup, its Analytics destination and
sample data, and environment shutdown.
Refs #50420
diff --git a/docs/extensions/extension-onboarding/handling-merchant-onboarding.md b/docs/extensions/extension-onboarding/handling-merchant-onboarding.md
index bcf8f14c472..4c4591aa171 100644
--- a/docs/extensions/extension-onboarding/handling-merchant-onboarding.md
+++ b/docs/extensions/extension-onboarding/handling-merchant-onboarding.md
@@ -318,7 +318,7 @@ add_action( 'admin_enqueue_scripts', 'add_task_register_script' );
By following these steps, your custom task should appear in the WooCommerce onboarding tasklist.
-For a complete example of adding a custom task as a WordPress plugin, you can check out the [add-task examples directory](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/client/admin/docs/examples/extensions/add-task).
+The extension scaffolded in this guide uses the maintained [`add-task` variant](https://github.com/woocommerce/woocommerce/tree/trunk/packages/js/create-woo-extension#onboarding-variants).
To learn more about the tasklist, you can refer to the [tasklist documentation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/admin/docs/features/onboarding-tasks.md).
diff --git a/plugins/woocommerce/changelog/fix-admin-extension-example-documentation b/plugins/woocommerce/changelog/fix-admin-extension-example-documentation
new file mode 100644
index 00000000000..256d2ea2042
--- /dev/null
+++ b/plugins/woocommerce/changelog/fix-admin-extension-example-documentation
@@ -0,0 +1,3 @@
+Significance: patch
+Type: dev
+Comment: Fix Admin extension example docs and remove an obsolete example; no production change.
diff --git a/plugins/woocommerce/client/admin/CLAUDE.md b/plugins/woocommerce/client/admin/CLAUDE.md
index 838b167fdde..ed4846c22f6 100644
--- a/plugins/woocommerce/client/admin/CLAUDE.md
+++ b/plugins/woocommerce/client/admin/CLAUDE.md
@@ -490,18 +490,12 @@ Coverage reports help identify untested code paths.
### Extension Development
-The `docs/examples/extensions/` directory contains examples for:
+Report, task, dashboard section, SQL and table column examples are `@woocommerce/create-woo-extension` variants (`packages/js/create-woo-extension/`).
-- Adding custom reports
-- Creating inbox notifications
-- Adding dashboard sections
-- Creating custom tasks
-- Modifying tables and columns
-
-To build examples:
+`docs/examples/extensions/` holds a few smaller examples. Build one by naming its directory in `WC_EXT`; see `docs/examples/extensions/README.md`:
```bash
-pnpm run example
+WC_EXT=simple-inbox-note pnpm run example
```
### Changelog Management
diff --git a/plugins/woocommerce/client/admin/docs/examples/extensions/README.md b/plugins/woocommerce/client/admin/docs/examples/extensions/README.md
index de7931ea86c..80d06ca4a5e 100644
--- a/plugins/woocommerce/client/admin/docs/examples/extensions/README.md
+++ b/plugins/woocommerce/client/admin/docs/examples/extensions/README.md
@@ -1,29 +1,67 @@
# WooCommerce Admin Extension Examples
-Examples for extending WooCommerce Admin
+Choose the workflow that matches the example you want to try:
-## Directions
+- **Inbox note:** [Build an example from this directory](#build-an-example-from-this-directory) using the WooCommerce monorepo. The `simple-inbox-note` example adds a note to **WooCommerce > Home**.
+- **Analytics report or onboarding task:** [Scaffold a standalone extension](#scaffold-a-standalone-extension). The former `add-report` and `add-task` examples now use this workflow and do not require a WooCommerce checkout.
-Install dependencies, if you haven't already.
+## Build an example from this directory
+
+This directory holds smaller examples for contributors working in the WooCommerce monorepo. Start from a checkout that is set up and built as described in the repository's [Getting Started guide](../../../../../../../README.md#getting-started), and have Docker running for wp-env.
+
+`WC_EXT` is a shell environment variable, not a command. Set it to the name of an example directory and run the `example` script of `@woocommerce/admin-library` from the monorepo root:
```bash
-pnpm install
+WC_EXT=simple-inbox-note pnpm --filter=@woocommerce/admin-library example
+```
+
+This copies the example to `plugins/woocommerce/client/simple-inbox-note` and compiles its JavaScript into that directory's `dist/` folder.
+
+To load it in the WooCommerce wp-env, add it to the `plugins` list in `plugins/woocommerce/.wp-env.override.json`, keeping `.` (WooCommerce) and any entries you already have:
+
+```json
+{
+ "plugins": [
+ ".",
+ "./client/simple-inbox-note"
+ ]
+}
```
-Build the example extension by running the pnpm script and passing the example name.
+Run `pnpm wc:env` from the monorepo root to apply the change. wp-env activates the plugins in this list, and activating the example adds its note. Open **WooCommerce > Home** in WordPress admin to see the "Hello From Inbox Note!" note in the inbox. If Home opens the setup wizard instead, select **Skip guided setup**, choose your store's country or region, and select **Go to my store**.
+
+## Edit the example
+
+Edit the files in `simple-inbox-note/` under this directory, not the generated copy, and run the `example` command again. The note is stored when the plugin is activated, so rebuilding alone does not update it. Under **Plugins > Installed Plugins**, deactivate and reactivate **WooCommerce Admin Simple Inbox Note Example**, then reload **WooCommerce > Home** to see your changes.
+## Clean up
+
+1. Under **Plugins > Installed Plugins**, deactivate **WooCommerce Admin Simple Inbox Note Example**. This removes its note.
+2. Remove `./client/simple-inbox-note` from the `plugins` list in `plugins/woocommerce/.wp-env.override.json`, keeping `.` and any other entries.
+3. Delete the generated `plugins/woocommerce/client/simple-inbox-note` directory; Git does not ignore it.
+4. Run `pnpm wc:env` from the monorepo root to apply the configuration change.
+
+## Scaffold a standalone extension
+
+The former `add-report` and `add-task` examples now live in [`@woocommerce/create-woo-extension`](../../../../../../../packages/js/create-woo-extension/README.md), alongside other [variants](../../../../../../../packages/js/create-woo-extension/README.md#variants). The scaffold generates a standalone plugin with its own build and wp-env setup.
+
+For this walkthrough, use Node.js 24.15.0 or a newer 24.x release, npm, PHP, and Composer, and have Docker running. From a directory outside the WooCommerce checkout, generate the report example:
```bash
-WC_EXT=<example> pnpm --filter=@woocommerce/admin-library example
+npx @wordpress/create-block -t @woocommerce/create-woo-extension --variant=add-report my-extension-name
```
-You should see a new directory in `./woocommerce/plugins/{example} path.` Include the output plugin in your `.wp-env.json` or `.wp-env.override.json` and restart the WordPress instance. WooCommerce will now reflect the changes made by the example extension.
+Wait for dependency installation and the production build to finish. Then start the generated plugin's WordPress environment:
+
+```bash
+cd my-extension-name
+npx @wordpress/env start
+```
-You can make changes to Javascript and PHP files in the example and see changes reflected upon refresh.
+The included configuration installs and activates WooCommerce and the generated plugin. Open `/wp-admin/` at the site URL printed by wp-env and sign in with username `admin` and password `password`.
-## Example Extensions
+If WooCommerce opens the setup wizard, select **Skip guided setup**, choose your store's country or region, and select **Go to my store**.
-- `add-report` - Create a "Hello World" report page.
-- `add-task` - Create a custom task for the onboarding task list.
+Open **Analytics > My Extension Name**. You should see an **Example Data** table containing four sample apple varieties; no products or orders are needed. The report's admin URL is `/wp-admin/admin.php?page=wc-admin&path=%2Fanalytics%2Fmy-extension-name`.
-> **Note:** Some of the previous examples have been moved to the [@woocommerce/create-woo-extension](https://www.npmjs.com/package/@woocommerce/create-woo-extension) package as extension variants for easier scaffolding of new extensions. See the [Create Woo Extension README](../../../../../../../packages/js/create-woo-extension/README.md) for more information.
+When finished, run `npx @wordpress/env stop` from the generated plugin directory.
diff --git a/plugins/woocommerce/client/admin/docs/examples/extensions/important-admin-notice/js/index.js b/plugins/woocommerce/client/admin/docs/examples/extensions/important-admin-notice/js/index.js
deleted file mode 100644
index f5d189292f8..00000000000
--- a/plugins/woocommerce/client/admin/docs/examples/extensions/important-admin-notice/js/index.js
+++ /dev/null
@@ -1,36 +0,0 @@
-/**
- * External dependencies
- */
-
-import { addFilter } from '@wordpress/hooks';
-
-/**
- * Use the 'woocommerce_admin_notices_to_show' filter to add notices to show.
- */
-addFilter(
- 'woocommerce_admin_notices_to_show',
- 'plugin-domain',
- ( notices ) => {
- return [
- ...notices,
- // element id, [ classes to include ], [ classes to exclude ]
- [ null, [ 'woocommerce-admin' ], [ 'ok-to-hide' ] ],
- [ 'woocommerce-admin-important-notice', null, null ],
- ];
- }
-);
-
-/**
- * Use the 'woocommerce_admin_should_hide_notice' filter to show a specific notice by inspecting its children.
- */
-addFilter(
- 'woocommerce_admin_should_hide_notice',
- 'plugin-domain',
- ( hide, notice ) => {
- if ( hide && notice.querySelector( 'p.notice-text' ) ) {
- return false;
- }
-
- return hide;
- }
-);
diff --git a/plugins/woocommerce/client/admin/docs/examples/extensions/important-admin-notice/woocommerce-admin-important-admin-notice-example.php b/plugins/woocommerce/client/admin/docs/examples/extensions/important-admin-notice/woocommerce-admin-important-admin-notice-example.php
deleted file mode 100644
index 68b2a0ad44f..00000000000
--- a/plugins/woocommerce/client/admin/docs/examples/extensions/important-admin-notice/woocommerce-admin-important-admin-notice-example.php
+++ /dev/null
@@ -1,55 +0,0 @@
-<?php
-/**
- * Plugin Name: WooCommerce Admin Important Notice Example
- *
- * @package WooCommerce\Admin
- */
-
-/**
- * Register the JS.
- */
-function wc_admin_important_notice_register_script() {
- if ( ! class_exists( 'Automattic\WooCommerce\Internal\Admin\Loader' ) ) {
- return;
- }
-
- if (
- ! \Automattic\WooCommerce\Admin\PageController::is_admin_page() &&
- ! \Automattic\WooCommerce\Admin\PageController::is_embed_page()
- ) {
- return;
- }
-
- $asset_file = require __DIR__ . '/dist/index.asset.php';
- wp_register_script(
- 'wc-admin-important-notice',
- plugins_url( '/dist/index.js', __FILE__ ),
- $asset_file['dependencies'],
- $asset_file['version'],
- true
- );
-
- wp_enqueue_script( 'wc-admin-important-notice' );
-}
-add_action( 'admin_enqueue_scripts', 'wc_admin_important_notice_register_script' );
-
-/**
- * Create an Admin Notice we want to remain visible.
- */
-function wc_admin_add_important_notice() {
- ?>
- <div class="updated woocommerce-message">
- <p class="notice-text">Important notice targeted by inspecting DOM.</p>
- </div>
- <div class="updated woocommerce-admin woocommerce-message">
- <p>Important notice targeted by class.</p>
- </div>
- <div class="updated woocommerce-admin woocommerce-message ok-to-hide">
- <p>Notice excluded from importance clause targeted by class.</p>
- </div>
- <div id="woocommerce-admin-important-notice" class="updated woocommerce-message">
- <p>Important notice targeted by ID.</p>
- </div>
- <?php
-}
-add_action( 'admin_notices', 'wc_admin_add_important_notice' );
diff --git a/plugins/woocommerce/client/admin/docs/features/onboarding-tasks.md b/plugins/woocommerce/client/admin/docs/features/onboarding-tasks.md
index 3f4373b2b26..1cdd5fe7480 100644
--- a/plugins/woocommerce/client/admin/docs/features/onboarding-tasks.md
+++ b/plugins/woocommerce/client/admin/docs/features/onboarding-tasks.md
@@ -100,7 +100,7 @@ registerPlugin( 'add-task-list-item', {
### Example
-You can find a complete example of how to add a custom task as a WordPress plugin in the [examples directory](../examples/extensions/add-task/).
+You can scaffold a complete plugin with the maintained [`add-task` variant](../../../../../../packages/js/create-woo-extension/README.md#onboarding-variants).
## Models and classes
diff --git a/plugins/woocommerce/client/admin/docs/features/payment-gateway-suggestions.md b/plugins/woocommerce/client/admin/docs/features/payment-gateway-suggestions.md
index dd15e4d594b..5f925c1a7ee 100644
--- a/plugins/woocommerce/client/admin/docs/features/payment-gateway-suggestions.md
+++ b/plugins/woocommerce/client/admin/docs/features/payment-gateway-suggestions.md
@@ -4,16 +4,8 @@ This feature uses JSON to retrieve the currently recommended payment gateways. T
After merchants click on a recommendation, plugins from this source will then walk through an installer step, followed by a connection step with the minimum required fields for setup defined by the downloaded plugin.
-## Quick start
-
Gateway suggestions are retrieved from a REST API and can be added via a remote JSON data source or filtered with the `woocommerce_admin_payment_gateway_suggestion_specs` filter.
-To quickly get started with an example plugin, run the following:
-
-`WC_EXT=payment-gateway-suggestions pnpm example --filter=@woocommerce/admin-library`
-
-This will create a new plugin that when activated will add two new gateway suggestions. The first is a simple gateway demonstrating how configuration fields can be pulled from the gateway class to create a configuration form. The second gateway shows a more customized approach via SlotFill.
-
## Data Source Polling
If a store is opted into marketplace suggestions via `woocommerce_show_marketplace_suggestions` the suggestions by default will be retrieved from `https://woocommerce.com/wp-json/wccom/payment-gateway-suggestions/2.0/suggestions.json`.