Building WooCommerce Blocks with @wordpress/scripts and Webpack

To start developing WooCommerce Blocks, you need a solid development environment. In this guide, we’ll walk you through setting up a development environment for WooCommerce Blocks development.

Prerequisites

Before you proceed, ensure you have the following prerequisites installed:

1. WordPress: You should have a WordPress installation up and running, either locally or on a web server.
2. Node.js: Node.js is required for running JavaScript-based tools. You can download it from the official website, or check our guide for managing multiple NodeJS versions.
3. npm: npm is the package manager for Node.js, and it comes bundled with Node.js. Confirm its installation by running npm -v in your terminal.

Project Setup

Begin by setting up your package.json file with the following contents:

{
	"name": "woocommerce-block-example",
	"title": "woocommerce-block-example",
	"version": "1.0.0",
	"description": "WooCommerce Block Development.",
	"author": "CHLI Technologies",
	"keywords": [],
	"engines": {
		"node": ">=12.20.1",
		"npm": ">=6.14.0"
	},
	"devDependencies": {
		"@wordpress/scripts": "^14.0.0",
		"@woocommerce/dependency-extraction-webpack-plugin": "^1.7.0"
	},
	"scripts": {
		"start": "wp-scripts start",
		"build": "wp-scripts build",
		"check-engines": "wp-scripts check-engines",
		"format:js": "wp-scripts format resources/js",
		"lint:js": "wp-scripts lint-js resources/js",
		"lint:js-fix": "eslint resources/js --ext=js,jsx,ts,tsx --fix",
		"lint:js:report": "npm run lint:js -- --output-file eslint_report.json --ext=js,ts,tsx --format json"
	}
}

This package.json file sets up the basic project information, defines Node.js and npm version requirements, and lists the necessary development dependencies for WooCommerce Blocks development. It also includes scripts for starting, building, and linting your project.

Installing Dependencies

With your package.json file in place, navigate to your project directory using the terminal and run the following command to install the project’s dependencies:

npm install

This will install @wordpress/scripts and @woocommerce/dependency-extraction-webpack-plugin as specified in your package.json file.

Configuring Webpack

For general WooCommerce Blocks development, you can extend the default Webpack configuration provided by @wordpress/scripts. This extension will automatically include WooCommerce dependencies alongside WordPress dependencies.

Create a webpack.config.js file in your project directory and use the following code:

const defaultConfig = require('@wordpress/scripts/config/webpack.config');
const WooCommerceDependencyExtractionWebpackPlugin = require('@woocommerce/dependency-extraction-webpack-plugin');

module.exports = {
    ...defaultConfig,
    plugins: [
        ...defaultConfig.plugins.filter(
            (plugin) =>
                plugin.constructor.name !== 'DependencyExtractionWebpackPlugin'
        ),
        new WooCommerceDependencyExtractionWebpackPlugin(),
    ]
};

This configuration imports the default Webpack configuration from @wordpress/scripts and integrates the WooCommerceDependencyExtractionWebpackPlugin. It ensures that WooCommerce dependencies are extracted and included in your build.

Adding global aliases

Suppose you need to extend the checkout blocks and map an additional external global attribute. In this case, your webpack.config.js will look like this:

const defaultConfig = require('@wordpress/scripts/config/webpack.config');
const WooCommerceDependencyExtractionWebpackPlugin = require('@woocommerce/dependency-extraction-webpack-plugin');

const wcDepMap = {
    '@woocommerce/blocks-checkout': ['wc', 'blocksCheckout'],
};

const wcHandleMap = {
    '@woocommerce/blocks-checkout': 'wc-blocks-checkout',
};

const requestToExternal = (request) => {
    if (wcDepMap[request]) {
        return wcDepMap[request];
    }
};

const requestToHandle = (request) => {
    if (wcHandleMap[request]) {
        return wcHandleMap[request];
    }
};

module.exports = {
    ...defaultConfig,
    plugins: [
        ...defaultConfig.plugins.filter(
            (plugin) =>
                plugin.constructor.name !== 'DependencyExtractionWebpackPlugin'
        ),
        new WooCommerceDependencyExtractionWebpackPlugin({
            requestToExternal,
            requestToHandle,
        }),
    ]
};

In this extended example, we define mappings for the @woocommerce/blocks-checkout package, which allows you to extend and customize the checkout blocks. This ensures that your checkout block modifications are integrated seamlessly into WooCommerce.

Tip: We use this way of injecting the blocks-checkout global into the dependency manager because at the time of this article, the package is not yet part of WooCommerce’s dependency manager plugin.

Default Entry Points

Webpack is a powerful tool for bundling JavaScript and other assets. The default entry points for the @wordpress/scripts package are as follows:

JavaScript files are expected to reside in the root src folder, and they get compiled into the build folder.

Customizing Entry Points

If you prefer a different file structure, you can configure your own entry points. For example:

const defaultConfig = require('@wordpress/scripts/config/webpack.config');
const WooCommerceDependencyExtractionWebpackPlugin = require('@woocommerce/dependency-extraction-webpack-plugin');
const path = require('path');

module.exports = {
    ...defaultConfig,
    entry: {
        'blocks': './resources/js/blocks/index.js', // Customize your entry point here
    },
    output: {
        path: path.resolve(__dirname, 'assets/dist'), // Customize your output directory here
        filename: '[name].js',
    },
    plugins: [
        ...defaultConfig.plugins.filter(
            (plugin) =>
                plugin.constructor.name !== 'DependencyExtractionWebpackPlugin'
        ),
        new WooCommerceDependencyExtractionWebpackPlugin(),
    ]
};

In this example, the files are located in the resources folder, and they are compiled into the assets/dist folder. You can tailor this configuration to match your project’s structure and requirements.

That’s all! Happy coding!