84 lines
5.2 KiB
Markdown
84 lines
5.2 KiB
Markdown
---
|
||
post_title: How to build your first extension
|
||
menu_title: Build your first extension
|
||
tags: how-to
|
||
---
|
||
## Introduction
|
||
|
||
This guide will teach you how to use [create-woo-extension](https://www.npmjs.com/package/@woocommerce/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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/).
|
||
|
||
## Requirements
|
||
|
||
Before getting started, you will need the following tools installed on your device:
|
||
|
||
- [Node.js](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) with NPM
|
||
- [Docker](https://docs.docker.com/engine/install/) (must be running to use wp-env)
|
||
- [Composer](https://getcomposer.org/doc/00-intro.md)
|
||
|
||
This guide also presumes that you are familiar with working with the command line.
|
||
|
||
## Bootstrapping Your Extension
|
||
|
||
Open your terminal and run
|
||
|
||
```sh
|
||
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
|
||
|
||
```sh
|
||
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](https://make.wordpress.org/core/2020/03/03/wp-env-simple-local-environments-for-wordpress/). 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](http://localhost:8888/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](https://developer.woocommerce.com/docs/how-to-add-a-custom-field-to-simple-and-variable-products/)
|
||
|
||
## Reference
|
||
|
||
[Visit @woocommerce/create-woo-extension on NPM for package reference](https://www.npmjs.com/package/@woocommerce/create-woo-extension)
|
||
[Check out wp-env's command reference to learn more about advanced functionality](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/#command-reference)
|