Contents
Introduction
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 @woocommerce/admin-library@2.0.0-dev create-wc-extension node ./bin/starter-pack/starter-pack.js 🎉 Welcome to WooCommerce Admin Extension Starter Pack 🎉 What is the name of your extension? my-new-woocommerce-extension Wonderful, your extension has been scaffolded and placed as a sibling directory to this one. Run the following commands from the root of the extension and activate the plugin. npm install npm start
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, but you can easily modify it 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 architectures 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 supplemental PHP files with classes that encapsulate server-side functionality, as well as JavaScript and CSS assets that 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 src/ folder
This folder contains the JavaScript and SCSS files that shape the appearance and client-side behavior of your extension. The contents of this folder will eventually be transpiled and minified into browser-ready assets that your extension can register and enqueue in WordPress. When using the WooCommerce extension generator, you’ll have two starter files in this folder:
index.jsindex.scss
webpack.config.js
This is a configuration file for Webpack, which is a utility that you can use for preprocessing and bundling the JavaScript in your project so that it’s minified and ready to serve to a browser. Webpack is a highly configurable tool, which can make it intimidating if you haven’t worked with a modern JavaScript stack before. The WooCommerce extension generator outputs a straightforward configuration file with defaults preset to handle a lot of this configuration for you. If you use the generator to start an extension, your initial Webpack configuration may look something like this:
const defaultConfig = require( '@wordpress/scripts/config/webpack.config' );
const WooCommerceDependencyExtractionWebpackPlugin = require( '@woocommerce/dependency-extraction-webpack-plugin' );
module.exports = {
...defaultConfig,
plugins: [
...defaultConfig.plugins.filter(
( plugin ) =>
plugin.constructor.name !== 'DependencyExtractionWebpackPlugin'
),
new WooCommerceDependencyExtractionWebpackPlugin(),
],
};
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. You can read more about what this default configuration does in its package reference documentation and more about the purpose of dependency extraction in the README file for the WordPress Dependency Extraction Webpack Plugin’s README file.
Other important files
The WooCommerce extension generator adds a few hidden files to your extension’s root directory.
The .eslintrc.js file is a configuration file with a default set of instructions for linting the JavaScript in your extension using a common set of ESLint rules to which all WooCommerce extensions should adhere.
The .prettierrc.json file is a configuration file that loads a default set of Prettier rules for ensuring consistent code formatting across WooCommerce extensions.
While version control considerations are out of scope for this guide, it is highly recommended that you place your extension’s files under version control using Git. The WooCommerce extension generator adds a .gitignore file to your project that tells Git not to version-control the numerous superfluous files and build artifacts that get generated during the development process.
Finally, if your extension will be open-source, it’s important to include a LICENSE file at the top level of your project. There are a number of licenses you may choose from, but keep in mind that plugins listed in the WordPress.org plugin directory must be compatible with the GPLv2 license (or later). If you are planning to submit your extension to the WooCommerce Marketplace, be sure to review the Vendor Agreement when choosing a license.
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
←
Back: Getting Started
→