Setup @wordpress/scripts to compile your JS and SCSS scripts

When building a new WordPress theme, you’ll quickly realize that compiling SCSS to CSS is pretty much a necessity (because let’s be real, who wants to deal with plain CSS these days?). And don’t forget about minifying those CSS and JS files before sending them off into the wild.

Sure, you could roll your own custom webpack setup from scratch, but lucky for you, WordPress has a shiny little gift for us – the @wordpress/scripts module, designed specifically for this purpose. No need to reinvent the wheel!

We’ll be keeping things as simple as possible in this blog, focusing on the bare minimum setup—no unnecessary complications, just the essentials to get the job done.

This tutorial assumes you already have node, npm installed and are sufficiently proficient in them.

Step 1: Install the scripts package

Install the scripts using command.

npm install @wordpress/scripts --save-dev

Quick heads-up: As of writing this, the latest version of @wordpress/scripts is 30.10.0, and it’s not fully compatible with WordPress versions below 6.7. There’s a whole GitHub discussion about it here, but the TL;DR is:

Due to changes in block development dependencies, the latest version of @wordpress/scripts now relies on react-jsx-runtime instead of react. The problem? WordPress versions below 6.7 don’t include react-jsx-runtime, which can cause issues.

That said, this tutorial won’t dive into block development—our focus is strictly on setting up SCSS and JS, so you don’t need to worry about this unless you’re working with custom blocks.

You can now run these two command.

npx wp-scripts build

npx wp-scripts start

Step 2: Creating the custom webpack.config file

By default, the module looks for a src/ directory in the root of your theme or plugin. If you want to change that, you can use the --input flag to specify a different source directory. Similarly, the --output flag lets you define a custom location for your build files.

But here’s the catch—once your project grows, managing these flags manually can get messy. That’s why I believe it’s best to use a webpack.config.js file from the start. It keeps things organized and saves you from command-line gymnastics later on.

Webpack config file

/**
 * External dependencies
 */
const fs = require( 'fs' );
const path = require( 'path' );

/**
 * WordPress dependencies
 */
const defaultConfig = require( '@wordpress/scripts/config/webpack.config' );

const sharedConfig = {
	...defaultConfig,
	output: {
		path: path.resolve( process.cwd(), 'assets', 'build', 'js' ),
		filename: '[name].js',
		chunkFilename: '[name].js',
	},
	plugins: [
		...defaultConfig.plugins.filter(
			( plugin ) => plugin.constructor.name !== 'RtlCssPlugin'
		).map( ( plugin ) => {
			if ( plugin.constructor.name === 'MiniCssExtractPlugin' ) {
				plugin.options.filename = '../css/[name].css';
			}
			return plugin;
		}),
	],
	optimization: {
		...defaultConfig.optimization,
		splitChunks: {
			...defaultConfig.optimization.splitChunks,
		},
	},
};

const styles = {
	...sharedConfig,
	entry: () => {
		const entries = {};
		const dir = './assets/css';

		fs.readdirSync( dir ).forEach( ( fileName ) => {
			const fullPath = `${ dir }/${ fileName }`;
			if ( ! fs.lstatSync( fullPath ).isDirectory() ) {
				entries[ fileName.replace( /\.[^/.]+$/, '' ) ] = fullPath;
			}
		} );

		return entries;
	},
	module: {
		...sharedConfig.module,
	},
	plugins: [
		...sharedConfig.plugins.filter(
			( plugin ) => plugin.constructor.name !== 'DependencyExtractionWebpackPlugin',
		),
	],
};

const scripts = {
	...sharedConfig,
	entry: () => {
		const entries = {};
		const dir = './assets/js';

		fs.readdirSync( dir ).forEach( ( fileName ) => {
			const fullPath = `${ dir }/${ fileName }`;
			if ( ! fs.lstatSync( fullPath ).isDirectory() ) {
				entries[ fileName.replace( /\.[^/.]+$/, '' ) ] = fullPath;
			}
		} );

		return entries;
	}
}

module.exports = [
	styles,
	scripts,
];

Now that we have webpack.config.js in place, let’s quickly break down what it does. Instead of using the default @wordpress/scripts configuration as-is, we extend it to give us more control over where our compiled assets go.

• The output settings are modified so that JavaScript files are placed inside assets/build/js/ and CSS files inside assets/build/css/.
• We remove the RtlCssPlugin since we don’t need it, and tweak the MiniCssExtractPlugin to ensure styles are stored in the correct location.
• The config is split into two separate configurations—one for styles and one for scripts:
  • The styles config scans the assets/css/ folder and compiles all SCSS/CSS files.
  • The scripts config scans assets/js/ and compiles all JavaScript files.
• The DependencyExtractionWebpackPlugin is removed from the styles config because it’s not needed for CSS processing.

I am not going over every single line as every webpack.config file is different, but you can change the assets/js and assets/css path or add more paths if you wish to load your JS and CSS from somewhere else.

save above file as webpack.config.js at the root level of the theme.

Step 3: Update the scripts of the package.json

Now that we have the the webpack file in place, we can update the scripts object in the package.json file to use our own webpack config file.

  "scripts": {
    "start": "wp-scripts start --config ./webpack.config.js",
    "build": "wp-scripts build --config ./webpack.config.js"
  },

you can now run the command

npm run start

and

npm run build