Add stylesheet minification for bundled themes (Block themes) #10081

b1ink0 · 2025-09-29T18:31:07Z

TODO:

Stylesheet minification for Twenty Twenty-Two and Twenty Twenty-Five (Block themes).
~~Stylesheet minification for Twenty Nineteen, Twenty Twenty, and Twenty Twenty-One themes (Classic themes with existing build setup).~~
~~Stylesheet minification for classic themes without existing build setup.~~
~~Use Webpack instead of Gruntfile for a more streamlined workflow.~~
Update related GitHub workflow for handling stylesheet minification.
~~Add server-side or client-side minification of stylesheets.~~

Trac ticket: https://core.trac.wordpress.org/ticket/63012

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

Co-authored-by: Shyamsundar Gadde <shyamsundar.gadde@rtcamp.com>

…wenty-One themes Co-authored-by: Shyamsundar Gadde <shyamsundar.gadde@rtcamp.com>

…y Twenty, and Twenty Twenty-One theme stylesheet header comment Co-authored-by: Shyamsundar Gadde <shyamsundar.gadde@rtcamp.com>

github-actions · 2025-09-29T18:59:13Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

The Plugin and Theme Directories cannot be accessed within Playground.
All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

b1ink0 · 2025-09-29T20:03:59Z

cc: @westonruter

westonruter · 2025-09-30T01:15:29Z

@b1ink0 To make this easier to review and initially land, how about this initial PR be limited to just the block themes. To that end, could you revert the changes to all themes other than Twenty Twenty-Two and Twenty Twenty-Five? Once this is merged, we can then follow up with restoring the changes you currently have. Once we establish the pattern with the block themes, then it will be easier to then follow up with classic themes.

The highest priority is for the block themes well, since these are the ones which will be eligible to have their theme styles inlined, since they are very small. The classic themes will likely not be eligible for inlining, so the impact of minification will be less.

westonruter · 2025-09-30T01:19:52Z

src/wp-content/themes/twentytwentyfive/functions.php

+		$src = 'style.min.css';
+		if ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG || strpos( wp_get_wp_version(), '-src' ) || ! file_exists( get_parent_theme_file_path( 'style.min.css' ) ) ) {


In default-constants.php, the SCRIPT_DEBUG constant is always defined. So we don't need to check for it. This can also use str_contains() instead, since the polyfill was introduced in WP 5.9.

Suggested change

$src = 'style.min.css';

if ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG || strpos( wp_get_wp_version(), '-src' ) || ! file_exists( get_parent_theme_file_path( 'style.min.css' ) ) ) {

if ( SCRIPT_DEBUG || str_contains( wp_get_wp_version(), '-src' ) || ! file_exists( get_parent_theme_file_path( 'style.min.css' ) ) ) {

Note that when SCRIPT_DEBUG is defined, it will check the version to see if it contains -src as well.

When considering what core is doing for the emoji loader:

file_get_contents( ABSPATH . WPINC . '/js/wp-emoji-loader' . wp_scripts_get_suffix() . '.js' )

I think we can skip the file_exists() check as well.

If this were using get_stylesheet_uri() then we'd need the file_exists() check since it could be that the child theme has a style.css but not a style.min.css. But since we're only looking at the parent theme, then that isn't needed.

See #10081 (comment) for a suggestion to tie this together.

Note that when SCRIPT_DEBUG is defined, it will check the version to see if it contains -src as well.

Okay, default-constants.php is handling this, so the check can be removed without an issue.

If this were using get_stylesheet_uri() then we'd need the file_exists() check since it could be that the child theme has a style.css but not a style.min.css. But since we're only looking at the parent theme, then that isn't needed.

I have a doubt about this case. Currently, since we are not shipping minified files in the repo, the contributor needs to navigate to the theme and run npm run build to generate the minified files.

Let's say a core contributor is using the TT5 or TT2 theme and sets SCRIPT_DEBUG to false while debugging some other core scripts TT5 will then try to load the minified file, which doesn’t exist.

There are two solutions I can think of:

Keep the file existence check.

Create a new Webpack config that generates the minified files when npm run dev is run at the root level. (This is required because the Gruntfile only generates the minified files in the build folder.)

I believe this is to be expected. For example, if you force SCRIPT_DEBUG to be false in core without having done a build, you get all kinds of errors related to missing scripts and styles.

My bad, after setting SCRIPT_DEBUG to false and running npm run dev, it does generate the minified files for the theme in the src directory 😅.

src/wp-content/themes/twentytwentyfive/functions.php

src/wp-content/themes/twentytwentytwo/functions.php

westonruter · 2025-09-30T02:21:32Z

Results are looking good so far!

Twenty Twenty-Five

The stylesheet's size is reduced from 3.1 kB down to 0.8 kB, or ~75% smaller.

Before:

After:

Twenty Twenty-Two

The stylesheet's size is reduced from 6.6 kB down to 2.7 kB, or ~60% smaller.

…n, Twenty Twenty, and Twenty Twenty-One theme stylesheet header comment" This reverts commit 96cc018.

…Twenty Twenty-One themes" This reverts commit d3beb63.

Co-authored-by: Weston Ruter <westonruter@gmail.com>

westonruter · 2025-10-03T04:38:23Z

Can this be marked as ready for review as opposed to being a draft? It would be good to get more contributors who work on bundled themes to also look. It's looking good to me!

Update related GitHub workflow for handling stylesheet minification.

What is this about?

b1ink0 · 2025-10-03T04:48:23Z

Update related GitHub workflow for handling stylesheet minification.

What is this about?

Need to work on the deployment workflow of themes with a build step. There is already logic for handling T19, T20, and TT1, but need to add support for TT2 and TT5. ~~Will do it today~~.

github-actions · 2025-10-03T17:26:25Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @brotherk86k-lab.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

Core Committers: Use this line as a base for the props when committing in SVN:

Props b1ink0, westonruter, jorbin.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

…into feature/add-stylesheet-minification-for-bundled-themes

…es.yml workflow

westonruter · 2025-10-06T21:31:47Z

Need to work on the deployment workflow of themes with a build step. There is already logic for handling T19, T20, and TT1, but need to add support for TT2 and TT5.

@b1ink0 I've added these in f908cca and b83b6d0

westonruter

When I turn off SCRIPT_DEBUG with Twenty Twenty-Five:

-<link rel='stylesheet' id='twentytwentyfive-style-css' href='http://localhost:8000/wp-content/themes/twentytwentyfive/style.css?ver=1.3' media='all' />
+<link rel='stylesheet' id='twentytwentyfive-style-css' href='http://localhost:8000/wp-content/themes/twentytwentyfive/style.min.css?ver=1.3' media='all' />

And in Twenty Twenty-Two:

-<link rel='stylesheet' id='twentytwentytwo-style-css' href='http://localhost:8000/wp-content/themes/twentytwentytwo/style.css?ver=2.0' media='all' />
+<link rel='stylesheet' id='twentytwentytwo-style-css' href='http://localhost:8000/wp-content/themes/twentytwentytwo/style.min.css?ver=2.0' media='all' />

aaronjorbin · 2025-10-07T10:39:11Z

Gruntfile.js

 				src: [
 					'wp-admin/css/colors/*/*.css'
 				]
+			},


None of the other default themes are included. Is there a reason to only include these two?

Yes, in this PR only TT2 and TT5 have their stylesheets minified, other themes with a build step do not minify their stylesheets.

The idea is to start out with just minding the stylesheets for block themes since they are small and eligible to be inlined. Once we have a good workflow in place for block themes, we can follow up with minification for classic themes. However the performance gains won't be as large because the larger stylesheets wouldn't be eligible for inlining. A reduced size for an external stylesheet doesn't translate into as much of a performance boost as being able to eliminate that render blocking stylesheet in the first place, as I understand.

aaronjorbin · 2025-10-07T10:43:03Z

.gitignore

+/src/wp-content/themes/twentytwentytwo/node_modules
+/src/wp-content/themes/twentytwentyfive/node_modules
+
+# Minified files in bundled themes


I think this will have the effect of never shipping the minified files since the files won't be in the checked out code.

Yes, since the minified files are ignored, the ZIP files are being prepared from the repository without the minified files. See below:

wordpress-develop/.github/workflows/test-and-zip-default-themes.yml

Lines 216 to 230 in 73e822f

steps:

- name: Checkout repository

uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0

with:

ref: ${{ github.event_name == 'workflow_dispatch' && inputs.branch || github.ref }}

show-progress: ${{ runner.debug == '1' && 'true' || 'false' }}

persist-credentials: false

- name: Upload theme ZIP as an artifact

uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2

with:

name: ${{ matrix.theme }}

path: src/wp-content/themes/${{ matrix.theme }}

if-no-files-found: error

include-hidden-files: true

There are two options I can think of to resolve this:

We can include the minified files in the repo, similar to how classic themes require contributors to include the built CSS and CSS map files generated from SCSS files.

We could add a build step for TT2 and TT5 in the workflow for the bundle-theme job before the Upload theme ZIP as an artifact step is run.
This would work if the release of the bundled theme is handled through a GitHub workflow.
ref: https://make.wordpress.org/core/handbook/about/release-cycle/update-bundled-themes-2/#creating-theme-zip-files

cc: @westonruter

It sounds like the second option would be preferred, as I really don't like minified files being committed to the repo. For the classic themes using SASS it's a bit different because the changes to the .scss files at least result in changes to .css files which can get a clean diff. But for minified files, and changes just results in a lot of noise.

I will admit I don't have any experience with the theme release workflows, so I don't know specifically what is required to implement that second option.

I drafted the new bundle-theme job steps with assistance from Gemini Code Assist: 39bac29

aaronjorbin · 2025-10-07T11:16:10Z

src/wp-content/themes/twentytwentytwo/style.css

+/*
+ * IMPORTANT: This file is not normally served directly on the frontend, unless SCRIPT_DEBUG is enabled. For normal page
+ * loads, the `style.min.css` file will be served instead of `style.css` for improved performance. Because of this, if
+ * you make any changes to this file in the Theme File Editor, you will not normally see those changes reflected on the
+ * frontend. You would need to navigate to the theme directory in a terminal and run `npm install && npm run build`.
+ * Because of this, it is not recommended that you use the Theme File Editor to modify this stylesheet. Instead, you
+ * should add the necessary style overrides via "Additional CSS" in the Site Editor. If neither of these are an option,
+ * then you can modify `twentytwentytwo_styles()` in `functions.php` so that it never uses the minified file.
+ */


Suggested change

/*

* IMPORTANT: This file is not normally served directly on the frontend, unless SCRIPT_DEBUG is enabled. For normal page

* loads, the `style.min.css` file will be served instead of `style.css` for improved performance. Because of this, if

* you make any changes to this file in the Theme File Editor, you will not normally see those changes reflected on the

* frontend. You would need to navigate to the theme directory in a terminal and run `npm install && npm run build`.

* Because of this, it is not recommended that you use the Theme File Editor to modify this stylesheet. Instead, you

* should add the necessary style overrides via "Additional CSS" in the Site Editor. If neither of these are an option,

* then you can modify `twentytwentytwo_styles()` in `functions.php` so that it never uses the minified file.

*/

/*

* IMPORTANT: This file is only served on the frontend when `SCRIPT_DEBUG` is enabled;

* in most instances, the `style.min.css` file will be served. It is not recommended that you

* use the Theme File Editor to modify this stylesheet. Instead, add the necessary style

* overrides via "Additional CSS" in the Site Editor.

*/

There is no specific language standard for CSS, but for PHP the core standard are

Summaries should be clear, simple, and brief. Avoid describing “why” an element exists, rather, focus on documenting “what” and “when” it does something.

This aims to simplify and make the instructions a bit clearer. Further, build instructions belong in a readme file. Additionally, modifying a theme directly should be discouraged at every opportunity.

Starting this discussion here, but I think it applies to both style.css files

Done in 8ceb867.

Props jorbin 😄

Further, build instructions belong in a readme file.

I've added contributing.txt files to the two themes in a9e839c, adapted from twentynineteen.

…y-Five themes Co-authored-by: Jon Surrell <jonsurrell@git.wordpress.org>

Co-authored-by: Aaron Jorbin <jorbin@git.wordpress.org>

…ytwentyfive Co-authored-by: Aditya Dhade <aditya.dhade@rtcamp.com> Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

b1ink0 and others added 3 commits September 29, 2025 17:15

Add CSS minification for Twenty Twenty-Two and Twenty Twenty-Five themes

4d543ef

Co-authored-by: Shyamsundar Gadde <shyamsundar.gadde@rtcamp.com>

Add CSS minification for Twenty Nineteen, Twenty Twenty, and Twenty T…

d3beb63

…wenty-One themes Co-authored-by: Shyamsundar Gadde <shyamsundar.gadde@rtcamp.com>

Add re-minification instructions notice to the Twenty Nineteen, Twent…

96cc018

…y Twenty, and Twenty Twenty-One theme stylesheet header comment Co-authored-by: Shyamsundar Gadde <shyamsundar.gadde@rtcamp.com>

westonruter self-requested a review September 29, 2025 20:02

westonruter reviewed Sep 30, 2025

View reviewed changes

src/wp-content/themes/twentytwentyfive/functions.php Outdated Show resolved Hide resolved

westonruter reviewed Sep 30, 2025

View reviewed changes

src/wp-content/themes/twentytwentyfive/functions.php Outdated Show resolved Hide resolved

westonruter reviewed Sep 30, 2025

View reviewed changes

src/wp-content/themes/twentytwentyfive/functions.php Outdated Show resolved Hide resolved

westonruter reviewed Sep 30, 2025

View reviewed changes

src/wp-content/themes/twentytwentytwo/functions.php Outdated Show resolved Hide resolved

b1ink0 and others added 3 commits September 30, 2025 17:14

Revert "Add re-minification instructions notice to the Twenty Ninetee…

d2a352b

…n, Twenty Twenty, and Twenty Twenty-One theme stylesheet header comment" This reverts commit 96cc018.

Revert "Add CSS minification for Twenty Nineteen, Twenty Twenty, and …

0e2085e

…Twenty Twenty-One themes" This reverts commit d3beb63.

Improve documentation

d479361

Co-authored-by: Weston Ruter <westonruter@gmail.com>

b1ink0 changed the title ~~Add stylesheet minification for bundled themes~~ Add stylesheet minification for bundled themes (Block themes) Sep 30, 2025

Simplify stylesheet filename logic using SCRIPT_DEBUG suffix

0f0df2f

Co-authored-by: Weston Ruter <westonruter@gmail.com>

This comment was marked as spam.

Sign in to view

b1ink0 requested a review from westonruter October 1, 2025 16:55

b1ink0 marked this pull request as ready for review October 3, 2025 17:26

westonruter added 4 commits October 6, 2025 14:07

Merge branch 'trunk' of https://github.com/WordPress/wordpress-develop …

2a1d893

…into feature/add-stylesheet-minification-for-bundled-themes

Add twentytwentytwo and twentytwentyfive to test-and-zip-default-them…

f908cca

…es.yml workflow

Add dependabot configs for the themes

b83b6d0

Improve notice in style.css regarding minification process

3a9539d

Fix typo

b43e826

westonruter approved these changes Oct 6, 2025

View reviewed changes

westonruter requested review from karmatosed, desrosj and carolinan October 6, 2025 21:55

aaronjorbin reviewed Oct 7, 2025

View reviewed changes

b1ink0 and others added 4 commits October 7, 2025 16:51

Add TT2 and TT5 themes to workflow triggers

ff55cb6

Simplify notice in style.css for Twenty Twenty-Two and Twenty Twent…

8ceb867

…y-Five themes Co-authored-by: Jon Surrell <jonsurrell@git.wordpress.org>

Add contributing.txt files for npm usage

a9e839c

Co-authored-by: Aaron Jorbin <jorbin@git.wordpress.org>

Add steps to bundle-theme to minify CSS for twentytwentytwo and twent…

39bac29

…ytwentyfive Co-authored-by: Aditya Dhade <aditya.dhade@rtcamp.com> Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

		$src = 'style.min.css';
		if ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG \|\| strpos( wp_get_wp_version(), '-src' ) \|\| ! file_exists( get_parent_theme_file_path( 'style.min.css' ) ) ) {

	$src = 'style.min.css';
	if ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG \|\| strpos( wp_get_wp_version(), '-src' ) \|\| ! file_exists( get_parent_theme_file_path( 'style.min.css' ) ) ) {
	if ( SCRIPT_DEBUG \|\| str_contains( wp_get_wp_version(), '-src' ) \|\| ! file_exists( get_parent_theme_file_path( 'style.min.css' ) ) ) {

	steps:
	- name: Checkout repository
	uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
	with:
	ref: ${{ github.event_name == 'workflow_dispatch' && inputs.branch \|\| github.ref }}
	show-progress: ${{ runner.debug == '1' && 'true' \|\| 'false' }}
	persist-credentials: false

	- name: Upload theme ZIP as an artifact
	uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
	with:
	name: ${{ matrix.theme }}
	path: src/wp-content/themes/${{ matrix.theme }}
	if-no-files-found: error
	include-hidden-files: true

Add stylesheet minification for bundled themes (Block themes) #10081

Are you sure you want to change the base?

Add stylesheet minification for bundled themes (Block themes) #10081

Conversation

b1ink0 commented Sep 29, 2025 • edited by westonruter Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Sep 29, 2025

Test using WordPress Playground

Some things to be aware of

Uh oh!

b1ink0 commented Sep 29, 2025

Uh oh!

westonruter commented Sep 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

b1ink0 Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

westonruter commented Sep 30, 2025

Twenty Twenty-Five

Twenty Twenty-Two

Uh oh!

This comment was marked as spam.

westonruter commented Oct 3, 2025

Uh oh!

b1ink0 commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Unlinked Accounts

Uh oh!

westonruter commented Oct 6, 2025

Uh oh!

westonruter left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

b1ink0 Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

b1ink0 commented Sep 29, 2025 •

edited by westonruter

Loading

b1ink0 Sep 30, 2025 •

edited

Loading

b1ink0 commented Oct 3, 2025 •

edited

Loading

github-actions bot commented Oct 3, 2025 •

edited

Loading

b1ink0 Oct 7, 2025 •

edited

Loading