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/

[Taigistal]

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.