Set up Webpack For Your WordPress project

Hey WordPress developer! If you’re just getting started with WordPress, and want to learn how to set up package management and development, you’ve come to the right place. This guide will quickly walk you through how to set up webpack for your WordPress project. I’ll cover setting up webpack for vanilla Javascript along with SCSS which will compile to backwards compatible JS and CSS. Without further ado, let’s dive in!

Estimated reading time: 5 minutes

If you haven’t yet, please check out our WordPress Development Guide here to get everything you need to create a professional WordPress Project.

Install Node and NPM, (or Yarn) if you haven’t yet

If you don’t have Node or NPM installed yet, go ahead and follow the guide to install Node here. This is pretty simple. Once Node is installed you should be able to throw the code below in your terminal to confirm that it’s installed.

node -v

This command will give you the version of node you have installed. I’m currently on v20.11.1

Next if you’re using NPM as your package manager all you need to do is throw this in your terminal:

npm install -g

You can check that npm is installed by throwing this in the terminal:

npm -v

After you get npm installed you can install yarn if you want to do that. Below is the command, but for simplicities sake we’re going to assume you’re using npm for this project. To set up yarn instead simply follow the guides here.

npm install --global yarn

Install SCSS

First, to use SCSS in any of your projects you’ll need to install it globally. We’re going to use the node method since we know your system has node and npm.

npm install -g sass

Create a package.json file

Open your project up in your IDE and open the IDE’s terminal. Be sure you are located in your root project folder in your IDE. You’ll need to create a package.json file. Go ahead and use this command to fill in the necessary fields and get your package.json file set up with default values:

npm init -y

Install sass in your project

In your IDE terminal throw the following command in to install sass as a dev dependency:

npm i sass --save-dev

If you want to utilize WordPress coding standards for your SCSS, check out this easy guide on setting up Sylelint and Prettier configurations.

Install Webpack

In your IDE throw the following command in to install webpack along with webpack’s CLI tool.

npm i webpack webpack-cli --save-dev

Install the loaders you’ll need to build and bundle your project

Next up install the sass-loader, this is something webpack is going to need to load SCSS in development.

npm i sass-loader --save-dev

You’ll also need to install babel-loader and css-loader for your Javascript to be backwards compatible and for your SCSS to become CSS.

npm i babel-loader css-loader style-loader --save-dev

Finally, install the mini-css-extract-plugin for Webpack. This will build your SCSS into CSS:

npm i mini-css-extract-plugin --save-dev

Create a Webpack Configuration

To set up webpack for your WordPress project, we can create a webpack.config.js file in our root folder. This file will tell webpack to take our development files and build and bundle them for backwards compatibility. Before we do that, let’s first create a /dist folder in our root to tell webpack where to put our build files. Let’s also create a /src folder where we’ll have subfolders for js and scss like so:

/src/js
/src/scss

Go ahead and add a SCSS and JS file to these folders. I’ll call my JS file index.js and my style file block-styles.scss. These files are our “entry” points where webpack will take our development code from. The dist folder is where our code will end up once it’s been built by webpack.

Inside the webpack.config.js file add the following:

const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = {
	mode: 'production',
	entry: {
		main: [
			__dirname + '/src/js/index.js',
			__dirname + '/src/scss/block-styles.scss',
		],
	},
	output: {
		filename: '[name].js',
		path: __dirname + '/dist',
	},
	module: {
		rules: [
			{
				test: /\.js$/,
				exclude: /node_modules/,
				use: ['babel-loader'],
			},
			{
				test: /\.s[ac]ss$/i,
				use: [MiniCssExtractPlugin.loader, 'css-loader', 'sass-loader'],
			},
		],
	},
	plugins: [
		new MiniCssExtractPlugin({
			filename: '[name].css',
		}),
	]

If you want to ensure your Javascript is meeting WordPress coding standards, don’t miss this guide on setting up ESLint and Prettier WordPress configurations.

Using Development VS Production with Webpack

The above code will work for our “production” environment. You can see we’ve set the mode in the above file to “production”. If you want webpack to provide you with the bundle for the dev environment and the bundle for the build environment you’re probably best off splitting your webpack configurations into 2 separate files.

Create a webpack production config

Update the webpack.config.js file name to webpack.prod.js. Everything can stay the same.

Add a build script

In your package.json file create a key within the scripts key titled “build” like this below:

"build": "npx webpack"

Now in your terminal you can run npm run build and your new CSS and JS files should show up in your /dist folder.

Create a webpack development configuration

Duplicate the webpack.prod.js folder and change the new file to webpack.dev.js. Next update the file with the following changes. We’ve updated the mode, added a source map, and changed how our SCSS will be loaded by webpack.

module.exports = {
	mode: 'development',
	entry: {
		main: [
			__dirname + '/src/js/index.js',
			__dirname + '/src/scss/block-styles.scss',
		],
	},
	output: {
		filename: '[name].js',
		path: __dirname + '/dist',
	},
        devtool: 'inline-source-map',
	module: {
		rules: [
			{
				test: /\.js$/,
				exclude: /node_modules/,
				use: ['babel-loader'],
			},
			{
				test: /\.s[ac]ss$/i,
				use: ['style-loader'],
			},
		],
	},

That’s really all there is to getting started with setting up webpack for your WordPress project.

Enqueue your Bundled Styles and Scripts

Back in your plugin or theme main php file you need to tell WordPress where to find your newly bundled files so it can serve them to your users. For themes, this would be your functions.php file in the root directory, for plugins it’s most likely going to be the plugin-name.php file.

For CSS and Javascript for your theme

You should have a funcions.php file in your root theme directory. Add the following to see your newly bundled CSS and JS on your WordPress site.

/**
 * Proper way to enqueue scripts and styles.
 */
function theme_name_scripts() {
    wp_enqueue_style( 'main-style', get_template_directory_uri() . '/dist/main.css' );
    wp_enqueue_script( 'main-script', get_template_directory_uri() . '/dist/main.js', array(), '1.0.0', true );
}
add_action( 'wp_enqueue_scripts', 'theme_name_scripts' );

For your Plugin Scripts and Styles

If you’re developing a plugin you’ll just change the function slightly like this below. Be sure to add this code to your plugin-name.php file in your root directory.

function plugin_name_scripts() {
wp_enqueue_style( 
  'main-style', 
  plugin_dir_url( __FILE__ ). '/dist/main.css' 
);
wp_enqueue_script( 
  'main-script', 
  plugin_dir_url( __FILE__ ). '/dist/main.js', 
  array(), 
  '1.0.0', 
  true 
);
}
add_action( 'wp_enqueue_scripts', 'plugin_name_scripts' );

If your CSS is for blocks or the Full Site editor

If you want to include assets for custom blocks or styles or Javascript you want to see both on the front end and in the Full Site Editor use this code below:

/**
 * Enqueue content assets in the editor and front end.
 */
function example_enqueue_editor_assets() {
wp_enqueue_style( 
  'main-style', 
  plugin_dir_url( __FILE__ ). '/dist/main.css' 
  );
wp_enqueue_script( 
  'main-script', 
  plugin_dir_url( __FILE__ ). '/dist/main.js', 
  array(), 
  '1.0.0', 
  true 
);  
}
add_action( 'enqueue_block_assets', 'example_enqueue_editor_assets' );

Notice that the above code is using the plugins_url() function from WordPress. If you’re enqueueing assets for the FSE (Full Site Editor) in your theme, just make the folliwng changes:

wp_enqueue_style( 
  'main-style', 
  get_template_directory_uri() . '/dist/main.css' 
);

wp_enqueue_script( 
  'main-script', 
  get_template_directory_uri() . '/dist/main.js', 
  array(), 
  '1.0.0', 
  true 
 );

Photo by Kelli McClintock on Unsplash