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:

• Node.js with NPM
• Docker (must be running to use wp-env)
• Composer

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 here 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