Update build first extension doc (#44870)
* Init commit * Updates remainder of the doc * Fixes linting issues * Updates manifest from rebase * Updated manifest using command in this branch --------- Co-authored-by: Shani Banerjee <shanibanerjee@Shanis-MBP.lan>
This commit is contained in:
Shani
GitHub
parent
d0f095df72
commit
76b776d71c
|
|
@ -458,7 +458,7 @@
|
|||
"menu_title": "Build your first extension",
|
||||
"tags": "how-to",
|
||||
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/extension-development/building-your-first-extension.md",
|
||||
"hash": "0b72a7c7a844459c971f10ade3f56e5c172d6f4fe5902f733972aaf7fc2121cb",
|
||||
"hash": "6b3af5e8e96294df9625e843654adddcf97b26c81ec43b47c41be2b2ad835783",
|
||||
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/extension-development/building-your-first-extension.md",
|
||||
"id": "278c2822fe06f1ab72499a757ef0c4981cfbffb5"
|
||||
},
|
||||
|
|
@ -1204,5 +1204,5 @@
|
|||
"categories": []
|
||||
}
|
||||
],
|
||||
"hash": "2453d3ac64b6f1f4f4cd8efddfc166602f7182a9dff17218070fd2dccf8722e5"
|
||||
"hash": "919aaa18bc145996f6a7dc0259f810f29363cc12721bac513d0d4234b30c50a7"
|
||||
}
|
||||
|
|
@ -3,118 +3,84 @@ post_title: How to build your first extension
|
|||
menu_title: Build your first extension
|
||||
tags: how-to
|
||||
---
|
||||
## 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](https://react.dev/) user experience available in current versions of WordPress and WooCommerce.
|
||||
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:
|
||||
|
||||
## Using the extension generator
|
||||
There’s less boilerplate code to write, and less dependencies to manually setup
|
||||
Modern features such as Blocks are automatically supported
|
||||
Unit testing, linting, and Prettier IDE configuration are ready to use
|
||||
|
||||
Browse to your local WooCommerce Admin repository
|
||||
Once your extension is set up, we’ll 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’ll 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 you’re familiar with working with the command line.
|
||||
|
||||
## Bootstrapping Your Extension
|
||||
|
||||
Open your terminal and run
|
||||
|
||||
```sh
|
||||
cd /your/server/wp-content/plugins/woocommerce-admin
|
||||
npx @wordpress/create-block -t
|
||||
@woocommerce/create-woo-extension my-extension-name
|
||||
```
|
||||
|
||||
Run the extension generator command
|
||||
If you’d 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’s folder using
|
||||
|
||||
```sh
|
||||
npm run create-wc-extension
|
||||
cd my-extension-name
|
||||
```
|
||||
|
||||
The extension generator will scaffold out a basic extension and place it in its own plugin directory alongside WooCommerce on your local server.
|
||||
You should then install your extension’s dependencies using `npm install` and build it using `npm run build`.
|
||||
|
||||
The extension that the generator creates contains a simple [boilerplate](https://stackoverflow.com/questions/3992199/what-is-boilerplate-code) that handles much of the configuration needed for setting up a React-powered extension, which you can modify to fit your needs.
|
||||
Congratulations! You just spun up a WooCommerce extension! Your extension will have the following file structure:
|
||||
|
||||
## The architecture of a basic WooCommerce extension
|
||||
- `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’s 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
|
||||
|
||||
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](https://nodejs.org/en) 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](https://developer.wordpress.org/plugins/plugin-basics/best-practices/#architecture-patterns).
|
||||
## Setting Up a Developer Environment
|
||||
|
||||
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.
|
||||
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 don’t already have wp-env installed locally, you can install it using
|
||||
`npm -g i @wordpress/env`.
|
||||
|
||||
It will also contain files that are JavaScript and CSS assets which shape the client-side behavior and appearance.
|
||||
Once you’ve 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`.
|
||||
|
||||
## File structure generated by the `create-wc-extension script`
|
||||
If you didn’t 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`.
|
||||
|
||||
When you run the built-in extension generator, it will output something that looks similar to the structure below.
|
||||
## Next Steps
|
||||
|
||||
```sh
|
||||
- README.md
|
||||
- my-great-extension.php
|
||||
- package.json
|
||||
- src
|
||||
- index.js
|
||||
- index.scss
|
||||
- webpack.config.js
|
||||
```
|
||||
Now that you’ve bootstrapped your extension, it’s time to add some features! Here’s some simple ones you could include:
|
||||
|
||||
Here's a breakdown of what these files are and what purpose they serve:
|
||||
[How to add a custom field to simple and variable products](https://developer.woo.com/docs/how-to-add-a-custom-field-to-simple-and-variable-products/)
|
||||
|
||||
`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.
|
||||
## Reference
|
||||
|
||||
`[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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```sh
|
||||
cd /your/server/wc-content/plugins/your-extension/
|
||||
```
|
||||
|
||||
Then install the project's dependencies.
|
||||
|
||||
```sh
|
||||
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.
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
hello world
|
||||
```
|
||||
[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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue