woocommerce/docs/extension-development/building-your-first-extension.md

post_title
Building your first extension

The easiest way to get started building an extension is to use the built-in extension generator that is included alongside WooCommerce Admin. This utility is maintained as part of the codebase for WooCommerce Admin, so it includes up-to-date tools and many preconfigured settings for building modern extensions that take advantage of the React-powered user experience available in current versions of WordPress and WooCommerce.

Using the extension generator

Browse to your local WooCommerce Admin repository

cd /your/server/wp-content/plugins/woocommerce-admin

Run the extension generator command

npm run create-wc-extension

The extension generator will scaffold out a basic extension and place it in its own plugin directory alongside WooCommerce on your local server.

The extension that the generator creates contains a simple boilerplate that handles much of the configuration needed for setting up a React-powered extension, which you can modify to fit your needs.

The architecture of a basic WooCommerce extension

WooCommerce extensions use a combination of PHP and modern JavaScript to create a seamless user experience for merchants and shoppers that takes advantage of the features and functionality available in the NodeJS ecosystem while still being a good neighbor within the underlying WordPress application environment.

WordPress plugins (of which WooCommerce extensions are a specialized subset), tend to follow a few common patterns. You can read more about common WordPress plugin architecture in the Best Practices chapter of the WordPress Plugin Developer Handbook.

In addition to the main PHP file that all WordPress plugins must contain, a WooCommerce extension will typically contain additional PHP files with classes that assist in server-side functionality.

It will also contain files that are JavaScript and CSS assets which shape the client-side behavior and appearance.

File structure generated by the create-wc-extension script

When you run the built-in extension generator, it will output something that looks similar to the structure below.

.
├── README.md
├── my-great-extension.php
├── package.json
├── src
│   ├── index.js
│   └── index.scss
└── webpack.config.js

Here’s a breakdown of what these files are and what purpose they serve:

README.md This file is meant to have a high-level overview of your extension to make it easier for people to use and extend your project. The generator outputs a basic file with some minimal instructions in it to get you started, but you should replace the contents of the file with information specific to your project. It’s important to keep in mind that this file is not the same as the readme.txt file required by WordPress.org plugin directory, which must adhere to specific file standads.

[your-extension-name].php This is your extension’s main PHP file. It functions as the entry point for your extension and is where you’ll likely include code that hooks your extension into WordPress and WooCommerce. You can read more about the purpose of this file in the Getting Started section of the WordPress Plugin Developer Handbook.

package.json This is a manifest file that Node uses for a number of different purposes. It can store configuration settings for tools, lists of dependencies, aliases for common scripts, and even metadata about your extension. The WooCommerce extension generator outputs a package.json file that will bundle many helpful dependencies with your extension, as well as a variety of scripts you can use in conjunction with these dependencies to streamline your workflow and make sure your extension conforms to the same standards as other WordPress plugins and WooCommerce extensions. Here’s an example of what your package.json file might look like initially:

{
    "name": "my-great-extension",
    "title": "my-great-extension",
    "license": "GPL-3.0-or-later",
    "version": "0.1.0",
    "description": "my-great-extension",
    "scripts": {
        "build": "wp-scripts build",
        "check-engines": "wp-scripts check-engines",
        "check-licenses": "wp-scripts check-licenses",
        "format:js": "wp-scripts format-js",
        "lint:css": "wp-scripts lint-style",
        "lint:js": "wp-scripts lint-js",
        "lint:md:docs": "wp-scripts lint-md-docs",
        "lint:md:js": "wp-scripts lint-md-js",
        "lint:pkg-json": "wp-scripts lint-pkg-json",
        "packages-update": "wp-scripts packages-update",
        "start": "wp-scripts start",
        "test:e2e": "wp-scripts test-e2e",
        "test:unit": "wp-scripts test-unit-js"
    },
    "devDependencies": {
        "@wordpress/scripts": "^12.2.1",
        "@woocommerce/eslint-plugin": "1.1.0",
        "@woocommerce/dependency-extraction-webpack-plugin": "1.1.0"
    }
}

The settings in this autogenerated file tell Webpack to use the default configuration included with the @wordpress/scripts package (listed in your package.json as a development dependency) and to override the plugin it uses for dependency extraction with one that is tailor-made for WooCommerce extensions.

Try out your extension

If you used the extension generator to create your extension, you’ll need to complete a few final steps to see it in action.

First, navigate to your extension’s root directory on your development server:

cd /your/server/wc-content/plugins/your-extension/

Then install the project’s dependencies.

npm install

Finally, run the start script to generate an initial build of your extension. This script will also continuously watch your local files for changes.

npm start

Once your initial build is complete, you can browse to the administrative area of your local WordPress environment and activate your extension. If everything worked as it should, you should see a message in your browser’s JavaScript console:

hello world