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.

[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.