How to use wp-scripts for theme developing?

[cawa-93]

I want to set up a modern environment for theme development. I would like to use wp-scripts to automatically process the JS, CSS, SCSS as it is done for blocks.
I can't use FSE because my layout is too complicated, so I'm creating a more classic theme. Nevertheless, I want to use theme.json to customize colors, typography, blocks, etc...

I really miss guides on how to work with themes.
There is @wordpress/create-block, but there is no @wordpress/create-theme.

[t-hamano]

Hi @cawa-93,

There are various ways to build JS and SCSS for a theme, but below is an example of a script that I often use.

package.json

{
	"name": "my-theme",
	"scripts": {
		"start:sass": "sass src/sass/one.scss:build/css/one.css src/sass/two.scss:build/css/two.css --watch",
		"start:js": "wp-scripts start src/js/one.js src/js/two.js --output-path=build/js",
		"build:sass": "sass src/sass/one.scss:build/css/one.css src/sass/two.scss:build/css/two.css --no-source-map --style compressed",
		"build:js": "wp-scripts build src/js/one.js src/js/two.js --output-path=build/js",
		"clean": "rimraf build"
	},
	"devDependencies": {
		"@wordpress/scripts": "^26.13.0"
	}
}

[chimok]

Hello @cawa-93,

there's no separate guide or tutorial because it works exactly the same way.
You install @wordpress/scripts and use it to build the assets, there's no difference.

[cawa-93]

@chimok Ok. Let's say I have src/assets/styles folder with some scss files. How to compile whole folder into css files using @wordpress/scripts with .asset.php auto-generation?

[chimok]

@cawa-93 wp-script does search for the entry points in ./src and looks for index.js oder index.ts. So in your case you need to configure the entry points or simply use the default ./src/index.js.

Oh, and one advise, it looks like this is your first time using a bundler? Stop the habit to separate styles in src/styles and scripts in src/scripts then images in src/images. Think in "bundle", put everything (code, images) that belongs together in a folder like src/myfeature .....this is the idea how bundler works.

[vicobot-0815]

You might find this article by Justin Tadlock helpful:
Beyond block styles, part 1: using the WordPress scripts package with themes
https://developer.wordpress.org/news/2023/07/beyond-block-styles-part-1-using-the-wordpress-scripts-package-with-themes/

There are plenty more really good articles on that blog, under the "Theme" tag, but also for other development topics.

[onetrev]

I agree with @vicobot-0815 that Justin's tutorial post is very helpful. And good news! There is also now (as of January 2024) official documentation for using the wp-scripts package for a theme build process. That can be found here: https://developer.wordpress.org/themes/advanced-topics/build-process/

[james0r]

I came looking for a way to compile custom theme assets as well as block detection and compilation from /src as wp-scripts start would do out of the box. Is this covered anywhere? I can't seem to get it working with the tutorial above. My blocks are detected but only block.json and render.php are rendered to a /build directory.

[t-hamano]

@james0r You may find the following discussion helpful.

#44010

[silaskoehler]

I have also just switched to working with wp-scripts. I found it helpful that pnpm workspaces come in handy when working with wp-scripts on plugins and themes at the same time.

[stefanfisk]

Does anyone have any pointer on how to use wp-scripts with a theme that also contains blocks? I only do custom one-off themes and putting blocks in their own plugin feels messy when they have a hard coupling to the theme. I understand that I could just import the block files into the theme files, but I'd really like to keep them separately so that block resources are only loaded when needed.

[vicobot-0815]

Here are two sample repos with themes that have various block-related stuff (variations, styles, ...) built in, maybe those can give you a starting point:

• https://github.com/WordPress/block-theme-examples
• https://github.com/x3p0-dev/x3p0-ideas by Justin Tadlock - the block stuff is in the /ressources/js folder

[vicobot-0815]

Justin presents these repos in
https://wordpress.tv/2023/12/19/developer-hours-modern-wordpress-development-with-the-wp-scripts-package/
starting at about 0:31 and 0:38, explaining for example how to adapt your webpack config.

[onetrev]

Hey @stefanfisk, I found this tutorial linked below to be a very helpful place to start. It's actually really quite easy to setup. Note, even if you are doing custom blocks instead of ACF Blocks as shown in this tutorial, the same information applies. https://fullstackdigital.io/blog/how-to-build-multiple-acf-blocks-within-a-single-plugin-or-theme/

[james0r]

I just stumbled upon this starter theme which seems really solid https://github.com/bacoords/block-theme. I'm using it for reference atm.

[jinsley8]

I have /src with subfolders: blocks, js, scss and use this package.json script and webpack config that compiles blocks and assets.

I added the --webpack-copy-php flag to copy PHP files of ACF blocks so you can have regular static/dynamic blocks and ACF blocks.

/src
├── blocks/
├── js/
├── scss/
│   ├── editor.scss
│   ├── global.scss

// package.json
{
"scripts": {
		"build": "wp-scripts build --webpack-src-dir=src --webpack-copy-php",
		"start": "wp-scripts start --webpack-src-dir=src --webpack-copy-php",
	},
}

// WordPress webpack config - webpack.config.js
import wpConfig from '@wordpress/scripts/config/webpack.config.js';

// Plugins
import RemoveEmptyScriptsPlugin from 'webpack-remove-empty-scripts';
import CopyPlugin from 'copy-webpack-plugin';

// Utilities
import path from 'path';
import { globSync } from 'glob';

// Find all block.json files in the blocks directory
const blockJsonFiles = globSync('./src/blocks/**/block.json');

// Create entries object - scss and js files to compile
const entries = {
	// Block variations
	'assets/js/block-variations': './src/js/block-variations/index.js',

	// Styles
	// 'assets/css/editor': './src/scss/editor.scss',
};

// Add entries for each block
blockJsonFiles.forEach((jsonFile) => {
	const blockPath = path.dirname(jsonFile);
	const relativePath = path.relative('./src/blocks', blockPath);

	// Add index.js entry
	entries[`blocks/${relativePath}/index`] = `./${blockPath}/index.js`;

	// Check if view.js exists and add it as an entry
	const viewPath = path.join(blockPath, 'view.js');
	if (globSync(viewPath).length > 0) {
		entries[`blocks/${relativePath}/view`] = `./${blockPath}/view.js`;
	}
});

/**
 * Exports the custom webpack config.
 *
 * @since 1.0.0
 */
export default {
	...wpConfig,
	entry: entries,
	output: {
		...wpConfig.output,
		path: path.resolve(process.cwd(), 'build'),
		filename: '[name].js',
	},
	plugins: [
		// Include WordPress plugins but filter out RTL plugin
		...wpConfig.plugins.filter(
			(plugin) => plugin.constructor.name !== 'RtlCssPlugin'
		),

		// Remove empty JS files after WordPress asset generation
		new RemoveEmptyScriptsPlugin({
			stage: RemoveEmptyScriptsPlugin.STAGE_AFTER_PROCESS_PLUGINS,
		}),

		// Copy static assets
		// These are assets you want to copy directly
		new CopyPlugin({
			patterns: [
			        {
					from: './src/fonts',
					to: './assets/fonts',
				},
				{
					from: './src/js/vendors',
					to: './assets/js/vendors',
				},
			],
		}),
	],
	performance: {
		maxAssetSize: 512000,
	},
};

[Lovor01]

You could import assets in javascript, but that is a limited option (if they are importable - not all assets could be imported with import).
Otherwise, you can copy assets with CopyWebpackPlugin, by extending default webpack config. That's what I do sometimes.
If you import CSS with javascript (first option), you can use MiniCSSExtractPlugin to extract css in separate files in production. Otherwise it is bundled, which may not be optimal.

[robizzt]

I am also working with wp-scripts for theme developing. This is my theme structure:

theme/
- node_modules/
- assets/
-- css/
--- vendors/
---- other-css-files.css
--- style.css
-- js/
--- vendors/
---- other-js-files.js
--- script.js
-- images/
--- some images
- languages/
-- theme.pot
- parts/
-- some-part-1.html
-- some-part-2.html
- patterns/
-- some-pattern-1.php
-- some-pattern-2.php
- public/
-- files generated from "resources" folder
- resources/
-- editor and blocks folders and files
- templates/
-- index.html
-- some-template-1.html
-- some-template-2.html
- functions.php
- package-lock.json
- package.json
- screenshot.jpg
- style.css
- theme.json
- webpack.config.js

And what I want in my theme.zip archive is:

theme/
- assets/
-- css/
--- vendors/
---- other-css-files.css
--- style.css
-- js/
--- vendors/
---- other-js-files.js
--- script.js
-- images/
--- some images
- languages/
-- theme.pot
- parts/
-- some-part-1.html
-- some-part-2.html
- patterns/
-- some-pattern-1.php
-- some-pattern-2.php
- public/
-- files generated from "resources" folder
- templates/
-- index.html
-- some-template-1.html
-- some-template-2.html
- functions.php
- screenshot.jpg
- style.css
- theme.json

My solution was creating theme-zip.js file and when calling npm run theme-zip I would get exactly what I want.
You need to install npm install archiver --save-dev, add theme-zip.js in root of the theme, and in package.json add "theme-zip": "node theme-zip.js" under "scripts". npm run theme-zip will also run npm run build before creating theme.zip archive.

package.json

{
	"name": "theme",
	"version": "1.0.0",
	"license": "GPL-3.0-or-later",
	"main": "public/index.js",
	"scripts": {
		"build": "wp-scripts build",
		"start": "wp-scripts start",
		"format": "wp-scripts format",
		"lint:css": "wp-scripts lint-style",
		"lint:js": "wp-scripts lint-js",
		"packages-update": "wp-scripts packages-update",
		"theme-zip": "node theme-zip.js"
	},
	"devDependencies": {
		"@wordpress/scripts": "^30.6.0",
		"archiver": "^7.0.1"
	}
}

webpack.config.js

const defaultConfig = require('@wordpress/scripts/config/webpack.config');
const path = require('path');
module.exports = {
	...defaultConfig,
	entry: {
		...defaultConfig.entry,
		//index: './resources/index.js',
		//style: './resources/style.scss',
		'editor-script': './resources/editor.js',
		'editor-style': './resources/editor.scss'
	},
	output: {
		...defaultConfig.output,
		path: path.resolve(__dirname, 'public'),
		filename: '[name].js'
	}
};

theme-zip.js

const fs = require('fs');
const archiver = require('archiver');
const path = require('path');
const { exec } = require('child_process');


const rootFolderName = path.basename(__dirname);
const output = fs.createWriteStream(path.join(__dirname, `${rootFolderName}.zip`));
const themeArchive = archiver('zip', {
	zlib: { level: 9 }
});

output.on('close', function() {
	console.log(themeArchive.pointer() + ' total bytes');
});

themeArchive.on('error', function(err) {
	throw err;
});

themeArchive.pipe(output);

// Add your root folder names
const rootDirectories = [
	'assets',
	'languages',
	'parts',
	'patterns',
	'public',
	'templates'
];

// Add your root file names
const rootFiles = [
	'functions.php',
	'screenshot.jpg',
	'style.css',
	'theme.json'
];

exec('npm run build', (err, stdout, stderr) => {

	if (err) {
		console.error(`Error executing npm run build: ${err}`);
		return;
	}
	console.log(stdout);
	console.error(stderr);

	rootDirectories.forEach(dir => {
		themeArchive.directory(path.join(__dirname, dir), dir);
	});


	rootFiles.forEach(file => {
		themeArchive.file(path.join(__dirname, file), { name: file });
	});

	themeArchive.finalize();

});

[jinsley8]

@robizzt you can just use the wp-scripts plugin-zip script and add the files and folders you want included in the zip by listing them in package.json:

Package.json:

{
  "scripts": {
      "build": "wp-scripts build --webpack-src-dir=src --output-path=assets",
      "start": "wp-scripts start --webpack-src-dir=src --output-path=assets",
      "theme-zip": "wp-scripts plugin-zip"
  },
  // This tells theme-zip which files to include in the zip folder
  "files": [
      "acf-json/",
      "assets/",
      "inc/",
      "languages/",
      "parts/",
      "patterns/",
      "templates/",
      "*.php",
      "README.md",
      "LICENSE",
      "screenshot.png",
      "style.css",
      "theme.json"
  ],
}

[jinsley8]

If you're not building blocks in the theme then change the package.json script to build to a /assets folder.

The build and start scripts will compile to /assets.

In the /src/js folder I have individual JS files and enqueue separately.

/src
├── fonts/
├── js/
├── scss/
│   ├── editor.scss
│   ├── global.scss

Package.json:

{
  "scripts": {
      "build": "wp-scripts build --webpack-src-dir=src --output-path=assets",
      "start": "wp-scripts start --webpack-src-dir=src --output-path=assets",
      "theme-zip": "wp-scripts plugin-zip"
  },
  // This tells theme-zip which files to include in the zip folder
  "files": [
      "acf-json/",
      "assets/",
      "inc/",
      "languages/",
      "parts/",
      "patterns/",
      "templates/",
      "*.php",
      "README.md",
      "LICENSE",
      "screenshot.png",
      "style.css",
      "theme.json"
  ],
}

// WordPress webpack config - webpack.config.js
import wpConfig from '@wordpress/scripts/config/webpack.config.js';

// Plugins
import RemoveEmptyScriptsPlugin from 'webpack-remove-empty-scripts';
import CopyPlugin from 'copy-webpack-plugin';

// Utilities
import path from 'path';

/**
 * Exports the custom webpack config.
 *
 * @since 1.0.0
 */
export default {
	...wpConfig,
	entry: {
		'js/block-filters': path.resolve(
			process.cwd(),
			'src/js',
			'block-filters.js'
		),
		'js/block-styles': path.resolve(
			process.cwd(),
			'src/js',
			'block-styles.js'
		),
		'js/block-formats': path.resolve(
			process.cwd(),
			'src/js',
			'block-formats.js'
		),
		'css/global': path.resolve(process.cwd(), 'src/scss', 'global.scss'),
		'css/editor': path.resolve(process.cwd(), 'src/scss', 'editor.scss'),
	},
	plugins: [
		// Include WordPress plugins but filter out RTL plugin
		...wpConfig.plugins.filter(
			(plugin) => plugin.constructor.name !== 'RtlCssPlugin'
		),

		// Remove empty JS files after WordPress asset generation
		new RemoveEmptyScriptsPlugin({
			stage: RemoveEmptyScriptsPlugin.STAGE_AFTER_PROCESS_PLUGINS,
		}),

		// Copy static assets
		new CopyPlugin({
			patterns: [
				{
					from: './src/fonts',
					to: './fonts',
				},
			],
		}),
	],
	performance: {
		maxAssetSize: 512000,
	},
};

/**
 * Enqueue theme styles.
 */
function theme_enqueue_styles()
{
	$asset = include THEME_DIR . '/assets/css/global.asset.php';


	// Global styles for frontend
	wp_enqueue_style(
		'theme-global-styles',
		THEME_URI . '/assets/css/global.css',
		$asset['dependencies'],
		$asset['version']
	);
}
add_action('wp_enqueue_scripts', 'theme_enqueue_styles');

/**
 * Register styles with the editor
 */
function theme_editor_styles()
{
	add_editor_style([
		THEME_URI . '/assets/css/global.css',
	]);
}
add_action('after_setup_theme', 'theme_editor_styles');

/**
 * Enqueue editor styles and scripts
 */
function theme_enqueue_block_editor_assets()
{
	$filterAsset = include THEME_DIR . '/assets/js/block-filters.asset.php';
	$editorAsset = include THEME_DIR . '/assets/css/editor.asset.php';
	$blockFormatAsset = include THEME_DIR . '/assets/js/block-formats.asset.php';

	wp_enqueue_style(
		'theme-editor-styles',
		THEME_URI . '/assets/css/editor.css',
		$editorAsset['dependencies'],
		$editorAsset['version']
	);

	wp_enqueue_script(
		'theme-block-filters',
		THEME_URI . '/assets/js/block-filters.js',
		$filterAsset['dependencies'],
		$filterAsset['version'],
		true
	);

	wp_enqueue_script(
		'theme-block-formats',
		THEME_URI . '/assets/js/block-formats.js',
		array('wp-blocks', 'wp-i18n', 'wp-element', 'wp-editor', 'wp-rich-text'),
		$blockFormatAsset['version'],
		true
	);

	wp_enqueue_script(
		'theme-block-styles',
		THEME_URI . '/assets/js/block-styles.js',
		array('wp-blocks', 'wp-dom-ready'),
		$blockFormatAsset['version'],
		true
	);
}
add_action('enqueue_block_editor_assets', 'theme_enqueue_block_editor_assets');