Optimization & Cleanup Guide

This document outlines the strategies and processes used to optimize the theme for production, addressing key performance requirements such as critical CSS, asset preloading, and render-blocking resources.

1. Production Build & Tailwind Optimization

Goal: Optimize the loading of the Tailwind CSS file for production.

We use npm scripts to handle the build pipeline, ensuring assets are minified and ready for deployment.

Steps to Build

Open your terminal and navigate to the theme directory (wp-content/themes/wp-scratch).
Ensure dependencies are installed: npm install.
Run the build command:
```
npm run build
```

What it does:

Tailwind Compilation: Compiles src/input.css to style.css.
Minification: Uses the --minify flag to compress the CSS, removing whitespace and comments.
Purging: Tailwind's JIT engine automatically removes unused utility classes based on the content configuration in tailwind.config.js.
Critical CSS Generation: Triggers the scripts/generate-critical.mjs script.

Build Configuration Files

There isn't a single "build config" file; rather, the process is controlled by a few key files:

package.json: Defines the build script command (tailwindcss ... && node ...).
tailwind.config.js: Configures the CSS compilation, including the content paths for purging unused styles.
scripts/generate-critical.mjs: Configures the Critical CSS generation (viewport size, source URL, etc.).

2. Critical CSS Strategy

To improve "First Contentful Paint" (FCP) and Core Web Vitals, we generate and inline the CSS required for above-the-fold content.

Generation

Installation:

npm install --save-dev critical

The script scripts/generate-critical.mjs uses the critical NPM package.

Source: Fetches the local homepage URL defined in the script.
Output: Writes to critical.css in the theme root.
Dimensions: Targets a standard desktop viewport (1300x900) to determine what is "critical".

Implementation (`functions.php`)

Inlining: The wp_scratch_inline_critical_css function reads critical.css and prints it within <style> tags in the <head>.
Deferral: The wp_scratch_defer_styles filter modifies the main style.css link tag. It sets media="print" initially and switches to media="all" via JavaScript (onload), preventing the large stylesheet from blocking rendering.

3. Asset Optimization

Font Preloading

To reduce "Flash of Unstyled Text" (FOUT) and improve Cumulative Layout Shift (CLS), we preload key font files.

Function: wp_scratch_preload_fonts in functions.php.
Method: Adds <link rel="preload" ...> tags to the <head> for primary font files (e.g., IBM Plex Sans, Anybody).

Cache Busting

We ensure users always receive the latest assets after a deployment without needing a hard refresh.

Method: In wp_enqueue_scripts, we use filemtime() to get the file's modification timestamp and use it as the version number for style.css and custom scripts.

4. Code Cleanup Checklist

Before deploying to production, ensure the following steps are taken:

Remove Debugging: Delete console.log statements and temporary debug scripts (e.g., block registry loggers in admin_footer).
Disable Dev Helpers: Remove aggressive cache clearing actions (like wp_clean_themes_cache on init) used during development to prevent performance hits.
Verify Block Metadata: Ensure block.json files have correct titles, descriptions, and categories.
Check theme.json: Ensure no duplicate font definitions or unused palette colors remain.

5. Future Considerations

Image Optimization: Consider adding automated image compression (WebP generation) if not handled by a plugin.
Script Concatenation: If the number of custom block scripts grows significantly, consider a build step to bundle them, though HTTP/2 makes this less critical.

Created: March 17, 2026 • Last Modified: February 22, 2026

Docs Login