How to build your first extension
Introduction
This guide will teach you how to use create-woo-extension to scaffold a WooCommerce extension. There are various benefits to using create-woo-extension over manually creating one from scratch, including:
There is less boilerplate code to write, and fewer dependencies to manually setup.
Modern features such as Blocks are automatically supported, and unit testing, linting, and Prettier IDE configuration are ready to use.
Once your extension is set up, we will show you how to instantly spin up a development environment using wp-env.
Requirements
Before getting started, you will need the following tools installed on your device:
This guide also presumes that you are familiar with working with the command line.
Bootstrapping Your Extension
Open your terminal and run
npx @wordpress/create-block -t @woocommerce/create-woo-extension my-extension-name
If you would like to set a custom extension name, you can replace my-extension-name
with any slug. Please note that your slug must not have any spaces.
If you see a prompt similar to Need to install the following packages
: @wordpress/create-block@4.34.0. Ok to proceed?
, press Y
.
Once the package finishes generating your extension, navigate into the extension folder using
cd my-extension-name
You should then install the extension dependencies using npm install
and build it using npm run build
.
Congratulations! You just spun up a WooCommerce extension! Your extension will have the following file structure:
-
my-extension-name
-
block.json
– contains metadata used to register your custom blocks with WordPress. Learn more. -
build
– the built version of your extension which is generated using npm run build. You shouldn’t directly modify any of the files in this folder. -
composer.json
– contains a list of your PHP dependencies which is referenced by Composer. -
composer.lock
– this file allows you to control when and how to update these dependencies -
includes
– The primary purpose of an “includes” folder in PHP development is to store reusable code or files that need to be included or required in multiple parts of a project. This is a PHP developer convention. -
languages
– contains POT files that are used to localize your plugin. -
my-extension-name.php
– your plugin entry point that registers your plugin with WordPress. -
node-modules
– help you form the building blocks of your application and write more structured code -
package.json
– is considered the heart of a Node project. It records metadata, and installs functional dependencies, runs scripts, and defines the entry point of your application. -
README.md
– An introduction and instructional overview of your application. Any special instructions, updates from the author, and details about the application can be written in text here. -
src
– keeps the root directory clean and provides a clear separation between the source code and other assets -
tests
– can hold unit tests for your application, keeps them separate from source files -
vendor
– holds project dependencies, and 3rd party code that you did not write -
webpack.config.js
– webpack is a module bundler. Its main purpose is to bundle JavaScript files for usage in a browser
-
Setting Up a Developer Environment
We recommend using wp-env
to spin up local development environments. You can learn more about wp-env here. If you do not already have wp-env installed locally, you can install it using
npm -g i @wordpress/env
.
Once you have installed wp-env
, and while still inside your my-extension-name
folder, run wp-env
start. After a few seconds, a test WordPress site with your WooCommerce and your extension installed will be running on localhost:8888
.
If you did not set a custom name for your extension, you can visit wp-admin/admin.php?page=wc-admin&path=%2Fmy-extension-name
to see the settings page generated by /src/index.js. The default username/password combination for wp-env
is admin
/ password
.
Next Steps
Now that youâve bootstrapped your extension, you can finally add some features! Here are some simple ones you could include:
How to add a custom field to simple and variable products
Reference
Visit @woocommerce/create-woo-extension on NPM for package reference Check out wp-env’s command reference to learn more about advanced functionality
Last updated: December 05, 2024