woocommerce/docs/extension-development/building-your-first-extension.md

---
post_title: Building your first extension
---

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.

## Using the extension generator

Browse to your local WooCommerce Admin repository

```sh
cd /your/server/wp-content/plugins/woocommerce-admin
```

Run the extension generator command

```sh
npm run create-wc-extension
```

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](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.

## 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](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).

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.

It will also contain files that are JavaScript and CSS assets which 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.

```sh
- 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:

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