DEV Community: Martijn Assie

CLI Workflow for Generating WordPress Template Parts

Martijn Assie — Wed, 04 Feb 2026 14:06:11 +0000

Developer problem: "I need to create header/footer/sidebar for 15 client themes!!"

Manual approach:

Create header.php in each theme
Copy/paste navigation code
Create footer.php in each theme
Copy/paste widget areas
4 hours of repetitive work!!

My CLI approach:

Bash script + WP-CLI
Generate all template parts automatically
Consistent structure across themes
Done in 5 minutes!!

Here's how to automate WordPress template part generation with WP-CLI:

The Template Parts Problem

Block themes require:

/parts/header.html
/parts/footer.html
/parts/sidebar.html
/parts/navigation.html

Classic themes require:

header.php
footer.php
sidebar.php
navigation.php

For 15 client themes:

60 files to create manually
Copy/paste navigation menus
Copy/paste widget areas
Update theme-specific details
Massive time waste!!

Solution: WP-CLI + Bash Automation

The CLI Workflow

# Generate all template parts for a theme
./generate-template-parts.sh my-theme

# Output:
# ✓ Created /parts/header.html
# ✓ Created /parts/footer.html
# ✓ Created /parts/sidebar.html
# ✓ Created /parts/navigation.html
# Done in 8 seconds!!

Setting Up WP-CLI

Install WP-CLI

# Download WP-CLI
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar

# Make executable
chmod +x wp-cli.phar

# Move to system path
sudo mv wp-cli.phar /usr/local/bin/wp

# Verify installation
wp --version
# WP-CLI 2.10.0

Test WP-CLI Access

# Navigate to WordPress installation
cd /var/www/html

# List installed themes
wp theme list

# Output:
# +-----------------+----------+--------+---------+
# | name            | status   | update | version |
# +-----------------+----------+--------+---------+
# | twentytwentyfour| active   | none   | 1.0     |
# | my-theme        | inactive | none   | 1.0.0   |
# +-----------------+----------+--------+---------+

Block Theme Template Parts Generator

Script: generate-block-parts.sh

#!/bin/bash

# Usage: ./generate-block-parts.sh my-theme

THEME_SLUG=$1
THEME_DIR="/var/www/html/wp-content/themes/${THEME_SLUG}"
PARTS_DIR="${THEME_DIR}/parts"

# Validate theme exists
if [ ! -d "$THEME_DIR" ]; then
    echo "Error: Theme '${THEME_SLUG}' not found!"
    exit 1
fi

# Create parts directory
mkdir -p "$PARTS_DIR"

echo "Generating template parts for theme: ${THEME_SLUG}"

# Generate header.html
cat > "${PARTS_DIR}/header.html" << 'EOF'
<!-- wp:group {"align":"full","style":{"spacing":{"padding":{"top":"20px","bottom":"20px"}}},"layout":{"type":"constrained"}} -->
<div class="wp-block-group alignfull" style="padding-top:20px;padding-bottom:20px">
    <!-- wp:group {"layout":{"type":"flex","flexWrap":"nowrap","justifyContent":"space-between"}} -->
    <div class="wp-block-group">
        <!-- wp:site-logo {"width":120} /-->

        <!-- wp:group {"layout":{"type":"flex"}} -->
        <div class="wp-block-group">
            <!-- wp:navigation {"ref":123,"layout":{"type":"flex","setCascadingProperties":true,"justifyContent":"right"}} /-->

            <!-- wp:buttons -->
            <div class="wp-block-buttons">
                <!-- wp:button -->
                <div class="wp-block-button">
                    <a class="wp-block-button__link wp-element-button">Get Started</a>
                </div>
                <!-- /wp:button -->
            </div>
            <!-- /wp:buttons -->
        </div>
        <!-- /wp:group -->
    </div>
    <!-- /wp:group -->
</div>
<!-- /wp:group -->
EOF

echo "✓ Created ${PARTS_DIR}/header.html"

# Generate footer.html
cat > "${PARTS_DIR}/footer.html" << 'EOF'
<!-- wp:group {"align":"full","style":{"spacing":{"padding":{"top":"60px","bottom":"40px"}},"elements":{"link":{"color":{"text":"var:preset|color|base"}}}},"backgroundColor":"contrast","textColor":"base","layout":{"type":"constrained"}} -->
<div class="wp-block-group alignfull has-base-color has-contrast-background-color has-text-color has-background has-link-color" style="padding-top:60px;padding-bottom:40px">
    <!-- wp:columns -->
    <div class="wp-block-columns">
        <!-- wp:column -->
        <div class="wp-block-column">
            <!-- wp:heading {"level":4} -->
            <h4>About</h4>
            <!-- /wp:heading -->

            <!-- wp:paragraph -->
            <p>Company description goes here.</p>
            <!-- /wp:paragraph -->
        </div>
        <!-- /wp:column -->

        <!-- wp:column -->
        <div class="wp-block-column">
            <!-- wp:heading {"level":4} -->
            <h4>Quick Links</h4>
            <!-- /wp:heading -->

            <!-- wp:navigation {"ref":456,"orientation":"vertical"} /-->
        </div>
        <!-- /wp:column -->

        <!-- wp:column -->
        <div class="wp-block-column">
            <!-- wp:heading {"level":4} -->
            <h4>Contact</h4>
            <!-- /wp:heading -->

            <!-- wp:paragraph -->
            <p>Email: info@example.com<br>Phone: (555) 123-4567</p>
            <!-- /wp:paragraph -->
        </div>
        <!-- /wp:column -->
    </div>
    <!-- /wp:columns -->

    <!-- wp:separator {"style":{"spacing":{"margin":{"top":"40px","bottom":"20px"}}}} -->
    <hr class="wp-block-separator has-alpha-channel-opacity" style="margin-top:40px;margin-bottom:20px"/>
    <!-- /wp:separator -->

    <!-- wp:group {"layout":{"type":"flex","flexWrap":"nowrap","justifyContent":"space-between"}} -->
    <div class="wp-block-group">
        <!-- wp:paragraph -->
        <p>© 2026 Company Name. All rights reserved.</p>
        <!-- /wp:paragraph -->

        <!-- wp:social-links -->
        <ul class="wp-block-social-links">
            <!-- wp:social-link {"url":"https://twitter.com/","service":"twitter"} /-->
            <!-- wp:social-link {"url":"https://facebook.com/","service":"facebook"} /-->
            <!-- wp:social-link {"url":"https://instagram.com/","service":"instagram"} /-->
        </ul>
        <!-- /wp:social-links -->
    </div>
    <!-- /wp:group -->
</div>
<!-- /wp:group -->
EOF

echo "✓ Created ${PARTS_DIR}/footer.html"

# Generate sidebar.html
cat > "${PARTS_DIR}/sidebar.html" << 'EOF'
<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
    <!-- wp:heading {"level":3} -->
    <h3>Sidebar</h3>
    <!-- /wp:heading -->

    <!-- wp:search {"label":"Search","showLabel":false,"buttonText":"Search"} /-->

    <!-- wp:separator {"style":{"spacing":{"margin":{"top":"30px","bottom":"30px"}}}} -->
    <hr class="wp-block-separator has-alpha-channel-opacity" style="margin-top:30px;margin-bottom:30px"/>
    <!-- /wp:separator -->

    <!-- wp:latest-posts {"postsToShow":5,"displayPostDate":true,"displayFeaturedImage":true,"featuredImageSizeSlug":"thumbnail"} /-->

    <!-- wp:separator {"style":{"spacing":{"margin":{"top":"30px","bottom":"30px"}}}} -->
    <hr class="wp-block-separator has-alpha-channel-opacity" style="margin-top:30px;margin-bottom:30px"/>
    <!-- /wp:separator -->

    <!-- wp:categories /-->

    <!-- wp:separator {"style":{"spacing":{"margin":{"top":"30px","bottom":"30px"}}}} -->
    <hr class="wp-block-separator has-alpha-channel-opacity" style="margin-top:30px;margin-bottom:30px"/>
    <!-- /wp:separator -->

    <!-- wp:tag-cloud /-->
</div>
<!-- /wp:group -->
EOF

echo "✓ Created ${PARTS_DIR}/sidebar.html"

# Generate navigation.html
cat > "${PARTS_DIR}/navigation.html" << 'EOF'
<!-- wp:navigation {"ref":789,"layout":{"type":"flex","setCascadingProperties":true,"justifyContent":"center"}} /-->
EOF

echo "✓ Created ${PARTS_DIR}/navigation.html"

echo ""
echo "✅ All template parts generated successfully!"
echo "Location: ${PARTS_DIR}"

Make Script Executable

chmod +x generate-block-parts.sh

Run Script

./generate-block-parts.sh my-theme

[![ ](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1w9tyjbhofyq8hpzhybn.webp)](https://www.elegantthemes.com/affiliates/idevaffiliate.php?id=53476&url=73342)

# Output:
# Generating template parts for theme: my-theme
# ✓ Created /var/www/html/wp-content/themes/my-theme/parts/header.html
# ✓ Created /var/www/html/wp-content/themes/my-theme/parts/footer.html
# ✓ Created /var/www/html/wp-content/themes/my-theme/parts/sidebar.html
# ✓ Created /var/www/html/wp-content/themes/my-theme/parts/navigation.html
#
# ✅ All template parts generated successfully!

If you're building child themes for popular themes, check out my guide on Building a Child Theme for Avada: The Right Way.

Classic Theme Template Parts Generator

Script: generate-classic-parts.sh

#!/bin/bash

# Usage: ./generate-classic-parts.sh my-classic-theme

THEME_SLUG=$1
THEME_DIR="/var/www/html/wp-content/themes/${THEME_SLUG}"

if [ ! -d "$THEME_DIR" ]; then
    echo "Error: Theme '${THEME_SLUG}' not found!"
    exit 1
fi

echo "Generating classic template parts for theme: ${THEME_SLUG}"

# Generate header.php
cat > "${THEME_DIR}/header.php" << 'EOF'
<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<head>
    <meta charset="<?php bloginfo('charset'); ?>">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <?php wp_head(); ?>
</head>
<body <?php body_class(); ?>>
<?php wp_body_open(); ?>

<div id="page" class="site">
    <header id="masthead" class="site-header">
        <div class="container">
            <div class="site-branding">
                <?php
                if (has_custom_logo()) {
                    the_custom_logo();
                } else {
                    ?>
                    <h1 class="site-title">
                        <a href="<?php echo esc_url(home_url('/')); ?>">
                            <?php bloginfo('name'); ?>
                        </a>
                    </h1>
                    <?php
                }
                ?>
            </div>

            <nav id="site-navigation" class="main-navigation">
                <?php
                wp_nav_menu(array(
                    'theme_location' => 'primary',
                    'menu_id'        => 'primary-menu',
                    'container'      => false,
                ));
                ?>
            </nav>
        </div>
    </header>

    <main id="primary" class="site-main">
EOF

echo "✓ Created ${THEME_DIR}/header.php"

[![ ](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1w9tyjbhofyq8hpzhybn.webp)](https://www.elegantthemes.com/affiliates/idevaffiliate.php?id=53476&url=73342)

# Generate footer.php
cat > "${THEME_DIR}/footer.php" << 'EOF'
    </main><!-- #primary -->

    <footer id="colophon" class="site-footer">
        <div class="container">
            <div class="footer-widgets">
                <div class="footer-column">
                    <?php dynamic_sidebar('footer-1'); ?>
                </div>

                <div class="footer-column">
                    <?php dynamic_sidebar('footer-2'); ?>
                </div>

                <div class="footer-column">
                    <?php dynamic_sidebar('footer-3'); ?>
                </div>
            </div>

            <div class="site-info">
                <p>
                    &copy; <?php echo date('Y'); ?> 
                    <a href="<?php echo esc_url(home_url('/')); ?>">
                        <?php bloginfo('name'); ?>
                    </a>. 
                    All rights reserved.
                </p>
            </div>
        </div>
    </footer>
</div><!-- #page -->

<?php wp_footer(); ?>
</body>
</html>
EOF

echo "✓ Created ${THEME_DIR}/footer.php"

# Generate sidebar.php
cat > "${THEME_DIR}/sidebar.php" << 'EOF'
<aside id="secondary" class="widget-area">
    <?php if (is_active_sidebar('sidebar-1')) : ?>
        <?php dynamic_sidebar('sidebar-1'); ?>
    <?php else : ?>

        <section class="widget widget_search">
            <?php get_search_form(); ?>
        </section>

        <section class="widget widget_recent_entries">
            <h2 class="widget-title">Recent Posts</h2>
            <?php
            wp_get_archives(array(
                'type'            => 'postbypost',
                'limit'           => 5,
                'format'          => 'html',
                'show_post_count' => true
            ));
            ?>
        </section>

        <section class="widget widget_categories">
            <h2 class="widget-title">Categories</h2>
            <ul>
                <?php wp_list_categories(array(
                    'title_li' => '',
                    'show_count' => true
                )); ?>
            </ul>
        </section>

    <?php endif; ?>
</aside>
EOF

echo "✓ Created ${THEME_DIR}/sidebar.php"

# Generate navigation.php (template part)
cat > "${THEME_DIR}/navigation.php" << 'EOF'
<nav class="navigation pagination">
    <h2 class="screen-reader-text">Posts navigation</h2>
    <div class="nav-links">
        <?php
        global $wp_query;

        $big = 999999999;

        echo paginate_links(array(
            'base'      => str_replace($big, '%#%', esc_url(get_pagenum_link($big))),
            'format'    => '?paged=%#%',
            'current'   => max(1, get_query_var('paged')),
            'total'     => $wp_query->max_num_pages,
            'prev_text' => '<span aria-hidden="true">&laquo;</span> Previous',
            'next_text' => 'Next <span aria-hidden="true">&raquo;</span>',
        ));
        ?>
    </div>
</nav>
EOF

echo "✓ Created ${THEME_DIR}/navigation.php"

echo ""
echo "✅ All classic template parts generated successfully!"

For optimizing classic theme performance, see my article on Avada vs Elementor: Which Page Builder Wins.

Advanced: Multi-Theme Generator

Batch Process Multiple Themes

#!/bin/bash

# generate-all-themes.sh
# Generate template parts for all client themes

THEMES=(
    "client-a-theme"
    "client-b-theme"
    "client-c-theme"
    "agency-portfolio"
    "ecommerce-store"
)

for theme in "${THEMES[@]}"; do
    echo ""
    echo "=== Processing: $theme ==="
    ./generate-block-parts.sh "$theme"

    # Also generate functions.php additions
    ./add-template-support.sh "$theme"
done

echo ""
echo "🎉 Generated template parts for ${#THEMES[@]} themes!"

Add Theme Support Automatically

#!/bin/bash

# add-template-support.sh
# Add required theme support for template parts

THEME_SLUG=$1
FUNCTIONS_FILE="/var/www/html/wp-content/themes/${THEME_SLUG}/functions.php"

if [ ! -f "$FUNCTIONS_FILE" ]; then
    echo "Error: functions.php not found for theme '${THEME_SLUG}'!"
    exit 1
fi

# Backup original functions.php
cp "$FUNCTIONS_FILE" "${FUNCTIONS_FILE}.backup"

# Append template part registration
cat >> "$FUNCTIONS_FILE" << 'EOF'

/**
 * Register navigation menus
 */
function theme_register_nav_menus() {
    register_nav_menus(array(
        'primary' => __('Primary Menu', 'theme-textdomain'),
        'footer'  => __('Footer Menu', 'theme-textdomain'),
    ));
}
add_action('after_setup_theme', 'theme_register_nav_menus');

/**
 * Register widget areas
 */
function theme_widgets_init() {
    register_sidebar(array(
        'name'          => __('Sidebar', 'theme-textdomain'),
        'id'            => 'sidebar-1',
        'before_widget' => '<section id="%1$s" class="widget %2$s">',
        'after_widget'  => '</section>',
        'before_title'  => '<h2 class="widget-title">',
        'after_title'   => '</h2>',
    ));

    register_sidebar(array(
        'name'          => __('Footer 1', 'theme-textdomain'),
        'id'            => 'footer-1',
        'before_widget' => '<section id="%1$s" class="widget %2$s">',
        'after_widget'  => '</section>',
        'before_title'  => '<h2 class="widget-title">',
        'after_title'   => '</h2>',
    ));

    register_sidebar(array(
        'name'          => __('Footer 2', 'theme-textdomain'),
        'id'            => 'footer-2',
        'before_widget' => '<section id="%1$s" class="widget %2$s">',
        'after_widget'  => '</section>',
        'before_title'  => '<h2 class="widget-title">',
        'after_title'   => '</h2>',
    ));

    register_sidebar(array(
        'name'          => __('Footer 3', 'theme-textdomain'),
        'id'            => 'footer-3',
        'before_widget' => '<section id="%1$s" class="widget %2$s">',
        'after_widget'  => '</section>',
        'before_title'  => '<h2 class="widget-title">',
        'after_title'   => '</h2>',
    ));
}
add_action('widgets_init', 'theme_widgets_init');
EOF

echo "✓ Added theme support to functions.php"
echo "✓ Backup created: ${FUNCTIONS_FILE}.backup"

WP-CLI Integration

Create Navigation Menus Automatically

#!/bin/bash

# create-menus.sh
# Create and assign navigation menus via WP-CLI

THEME_SLUG=$1

echo "Creating navigation menus for theme: ${THEME_SLUG}"

# Create Primary Menu
PRIMARY_MENU_ID=$(wp menu create "Primary Menu" --porcelain)
echo "✓ Created Primary Menu (ID: ${PRIMARY_MENU_ID})"

# Add menu items
wp menu item add-post $PRIMARY_MENU_ID 1 --title="Home"
wp menu item add-post $PRIMARY_MENU_ID 2 --title="About"
wp menu item add-post $PRIMARY_MENU_ID 3 --title="Services"
wp menu item add-post $PRIMARY_MENU_ID 4 --title="Blog"
wp menu item add-post $PRIMARY_MENU_ID 5 --title="Contact"

echo "✓ Added 5 menu items to Primary Menu"

# Assign menu to location
wp menu location assign $PRIMARY_MENU_ID primary

echo "✓ Assigned Primary Menu to 'primary' location"

# Create Footer Menu
FOOTER_MENU_ID=$(wp menu create "Footer Menu" --porcelain)
echo "✓ Created Footer Menu (ID: ${FOOTER_MENU_ID})"

# Add footer menu items
wp menu item add-custom $FOOTER_MENU_ID "Privacy Policy" "/privacy-policy"
wp menu item add-custom $FOOTER_MENU_ID "Terms of Service" "/terms"
wp menu item add-custom $FOOTER_MENU_ID "Sitemap" "/sitemap"

echo "✓ Added 3 menu items to Footer Menu"

# Assign footer menu
wp menu location assign $FOOTER_MENU_ID footer

echo "✓ Assigned Footer Menu to 'footer' location"

echo ""
echo "✅ Navigation menus created and assigned!"

Complete Workflow Script

#!/bin/bash

# complete-theme-setup.sh
# Complete theme setup: parts + support + menus

THEME_SLUG=$1

if [ -z "$THEME_SLUG" ]; then
    echo "Usage: ./complete-theme-setup.sh <theme-slug>"
    exit 1
fi

echo "========================================="
echo "Complete Theme Setup: ${THEME_SLUG}"
echo "========================================="
echo ""

# Step 1: Generate template parts
echo "Step 1: Generating template parts..."
./generate-block-parts.sh "$THEME_SLUG"
echo ""

# Step 2: Add theme support
echo "Step 2: Adding theme support..."
./add-template-support.sh "$THEME_SLUG"
echo ""

# Step 3: Create navigation menus
echo "Step 3: Creating navigation menus..."
./create-menus.sh "$THEME_SLUG"
echo ""

# Step 4: Activate theme
echo "Step 4: Activating theme..."
wp theme activate "$THEME_SLUG"
echo "✓ Theme activated"
echo ""

echo "========================================="
echo "✅ Theme setup complete!"
echo "========================================="
echo ""
echo "Next steps:"
echo "1. Visit Site Editor to customize header/footer"
echo "2. Add content to widget areas"
echo "3. Configure theme.json settings"

For more on theme comparison and setup, check out Divi vs Avada: Why ThemeForest's #1 Seller Costs 5x More Long-Term.

CI/CD Integration

GitHub Actions Workflow

.github/workflows/theme-setup.yml:

name: Theme Setup

on:
  workflow_dispatch:
    inputs:
      theme_slug:
        description: 'Theme slug to set up'
        required: true

jobs:
  setup-theme:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup SSH
        uses: webfactory/ssh-agent@v0.7.0
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

      - name: Run theme setup
        run: |
          ssh user@server "cd /var/www/html && ./complete-theme-setup.sh ${{ github.event.inputs.theme_slug }}"

      - name: Notify Slack
        uses: 8398a7/action-slack@v3
        with:
          status: ${{ job.status }}
          text: 'Theme ${{ github.event.inputs.theme_slug }} setup complete!'
          webhook_url: ${{ secrets.SLACK_WEBHOOK }}

Real-World Scenario: Agency Workflow

Agency: 15 new client themes per month

Before automation:

Create header.php manually (15 × 30 min = 7.5 hours)
Create footer.php manually (15 × 30 min = 7.5 hours)
Create sidebar.php manually (15 × 20 min = 5 hours)
Create navigation menus (15 × 15 min = 3.75 hours)
23.75 hours per month!!

With CLI automation:

# Setup all 15 client themes
for i in {1..15}; do
    ./complete-theme-setup.sh "client-theme-$i"
done

# Total time: 15 × 1 minute = 15 minutes!!

Time savings: 23.75 hours → 15 minutes = 95% faster!!

ROI: Developer at $100/hr × 23.75 hours = $2,375 saved per month!!

Bottom Line

Stop manually creating template parts for every theme!!

CLI automation wins:

Bash scripts + WP-CLI
Generate all parts in seconds
Consistent structure across themes
15 minutes vs 24 hours = massive savings!!

My agency results:

Before:

4 hours per theme setup
Inconsistent template structure
Copy/paste errors

After:

1 minute automated setup
Perfect consistency across 50+ themes
Zero copy/paste errors!!

Setup time: 2 hours to create scripts

ROI: First month saved 23+ hours = instant payoff!!

For agencies building multiple themes: Template part automation is ESSENTIAL!!

Generate 60 template files automatically vs creating them manually = 95% time savings!! 🚀

This article contains affiliate links!

Using Puppeteer to Test WordPress Pages for Visual Regressions

Martijn Assie — Tue, 03 Feb 2026 22:50:18 +0000

Developer nightmare: "We updated the theme... the homepage layout is COMPLETELY broken!!"

The problem:

Theme/plugin update
CSS change breaks layout
Discovered AFTER deployment
Users already seeing broken site!!

My solution:

Puppeteer automated screenshots
Jest image comparison
CI/CD visual regression tests
Catches layout breaks BEFORE production!!

Here's how to automate visual regression testing for WordPress:

The Visual Regression Problem

Manual QA approach:

Update theme/plugin on staging
Manually check 20+ pages
Click through responsive views
Miss subtle layout shifts
Deploy to production
User reports broken mobile menu!!

Automated approach:

Update theme/plugin on staging
Run automated screenshot tests
Puppeteer compares 50+ pages automatically
Test fails on ANY visual difference
Fix BEFORE production!!

What is Visual Regression Testing?

Visual regression = comparing screenshots to detect unintended layout changes

How it works:

Baseline screenshot (reference image)
Current screenshot (after changes)
Pixel-by-pixel comparison
Fail if differences detected

Example scenario:

Baseline: Homepage hero section 600px height
Current: After CSS update, hero section 400px height
Comparison: Detects 200px difference
Test fails, prevents broken deployment!!

Setting Up Puppeteer + Jest

Project Structure

wordpress-visual-tests/
├── package.json
├── jest.config.js
├── tests/
│   ├── homepage.test.js
│   ├── single-post.test.js
│   ├── archive.test.js
│   └── woocommerce.test.js
├── __image_snapshots__/
│   ├── homepage-test-js-homepage-desktop-1-snap.png
│   └── homepage-test-js-homepage-mobile-1-snap.png
└── __diff_output__/
    └── homepage-test-js-homepage-desktop-1-diff.png

Step 1: Install Dependencies

npm init -y

npm install --save-dev \
  puppeteer \
  jest \
  jest-puppeteer \
  jest-image-snapshot

puppeteer = headless Chrome automation

jest = testing framework

jest-puppeteer = Jest + Puppeteer integration

jest-image-snapshot = screenshot comparison

Step 2: Configure Jest

jest.config.js:

module.exports = {
  preset: 'jest-puppeteer',
  testTimeout: 30000,
  setupFilesAfterEnv: ['./jest.setup.js'],
  testMatch: ['**/tests/**/*.test.js']
};

jest.setup.js:

const { toMatchImageSnapshot } = require('jest-image-snapshot');

expect.extend({ toMatchImageSnapshot });

Step 3: Configure Puppeteer

jest-puppeteer.config.js:

module.exports = {
  launch: {
    headless: true,
    args: [
      '--no-sandbox',
      '--disable-setuid-sandbox',
      '--disable-dev-shm-usage'
    ]
  },
  browserContext: 'default'
};

Writing Visual Regression Tests

Test 1: Homepage Desktop/Mobile

tests/homepage.test.js:

describe('Homepage Visual Tests', () => {
  let browser;
  let page;

  beforeAll(async () => {
    browser = await puppeteer.launch({
      headless: true
    });
    page = await browser.newPage();
  });

  afterAll(async () => {
    await browser.close();
  });

  test('Homepage Desktop', async () => {
    // Set desktop viewport
    await page.setViewport({
      width: 1920,
      height: 1080
    });

    // Navigate to homepage
    await page.goto('https://staging.yoursite.com', {
      waitUntil: 'networkidle0'
    });

    // Wait for hero section to load
    await page.waitForSelector('.hero-section');

    // Take screenshot
    const screenshot = await page.screenshot({
      fullPage: true
    });

    // Compare with baseline
    expect(screenshot).toMatchImageSnapshot({
      failureThreshold: 0.01, // 1% tolerance
      failureThresholdType: 'percent'
    });
  });

  test('Homepage Mobile', async () => {
    // Set mobile viewport (iPhone 12)
    await page.setViewport({
      width: 390,
      height: 844
    });

    await page.goto('https://staging.yoursite.com', {
      waitUntil: 'networkidle0'
    });

    await page.waitForSelector('.hero-section');

    const screenshot = await page.screenshot({
      fullPage: true
    });

    expect(screenshot).toMatchImageSnapshot({
      failureThreshold: 0.01,
      failureThresholdType: 'percent'
    });
  });
});

Test 2: Single Post Layout

tests/single-post.test.js:

describe('Single Post Visual Tests', () => {
  let page;

  beforeAll(async () => {
    page = await browser.newPage();
  });

  test('Single Post Desktop', async () => {
    await page.setViewport({ width: 1920, height: 1080 });

    await page.goto('https://staging.yoursite.com/sample-post/', {
      waitUntil: 'networkidle0'
    });

    // Wait for post content
    await page.waitForSelector('.entry-content');

    // Screenshot only content area (not sidebar)
    const element = await page.$('.post-content-wrapper');
    const screenshot = await element.screenshot();

    expect(screenshot).toMatchImageSnapshot({
      customSnapshotIdentifier: 'single-post-content-desktop',
      failureThreshold: 0.01,
      failureThresholdType: 'percent'
    });
  });

  test('Single Post Comments Section', async () => {
    await page.setViewport({ width: 1920, height: 1080 });

    await page.goto('https://staging.yoursite.com/sample-post/#comments', {
      waitUntil: 'networkidle0'
    });

    // Scroll to comments
    await page.evaluate(() => {
      document.querySelector('#comments').scrollIntoView();
    });

    // Screenshot comments section only
    const element = await page.$('#comments');
    const screenshot = await element.screenshot();

    expect(screenshot).toMatchImageSnapshot({
      customSnapshotIdentifier: 'single-post-comments',
      failureThreshold: 0.02,
      failureThresholdType: 'percent'
    });
  });
});

Test 3: WooCommerce Product Page

tests/woocommerce.test.js:

describe('WooCommerce Visual Tests', () => {
  let page;

  beforeAll(async () => {
    page = await browser.newPage();
  });

  test('Product Page Desktop', async () => {
    await page.setViewport({ width: 1920, height: 1080 });

    await page.goto('https://staging.yoursite.com/product/sample-product/', {
      waitUntil: 'networkidle0'
    });

    // Wait for product gallery
    await page.waitForSelector('.woocommerce-product-gallery');

    const screenshot = await page.screenshot({
      fullPage: true
    });

    expect(screenshot).toMatchImageSnapshot({
      customSnapshotIdentifier: 'product-page-desktop',
      failureThreshold: 0.01,
      failureThresholdType: 'percent'
    });
  });

  test('Product Page Add to Cart Button', async () => {
    await page.setViewport({ width: 1920, height: 1080 });

    await page.goto('https://staging.yoursite.com/product/sample-product/', {
      waitUntil: 'networkidle0'
    });

    // Screenshot add to cart section only
    const element = await page.$('.product_meta');
    const screenshot = await element.screenshot();

    expect(screenshot).toMatchImageSnapshot({
      customSnapshotIdentifier: 'add-to-cart-section',
      failureThreshold: 0.01,
      failureThresholdType: 'percent'
    });
  });
});

If you're optimizing WooCommerce performance, check out my guide on Avada Theme WooCommerce Speed: From Slow to Fast.

Running Tests

First Run (Generate Baselines)

npm test

# Output:
# PASS  tests/homepage.test.js
#   ✓ Homepage Desktop (4523ms)
#   ✓ Homepage Mobile (3821ms)
#
# Snapshots:   2 written, 2 total

Baselines saved in image_snapshots/ directory!!

Subsequent Runs (Compare)

npm test

# Output if NO changes:
# PASS  tests/homepage.test.js
#   ✓ Homepage Desktop (4312ms)
#   ✓ Homepage Mobile (3654ms)
#
# Snapshots:   2 passed, 2 total

# Output if changes detected:
# FAIL  tests/homepage.test.js
#   ✗ Homepage Desktop (4421ms)
#
# Expected image to match or be a close match to snapshot
# but was 2.34% different from snapshot
#
# See diff at: __diff_output__/homepage-test-js-homepage-desktop-1-diff.png

Update Baselines (After Intentional Changes)

npm test -- --updateSnapshot

# or add to package.json:
# "test:update": "jest --updateSnapshot"

npm run test:update

Advanced Testing Scenarios

Test Multiple Viewports

const viewports = [
  { name: 'Desktop', width: 1920, height: 1080 },
  { name: 'Laptop', width: 1366, height: 768 },
  { name: 'Tablet', width: 768, height: 1024 },
  { name: 'Mobile', width: 390, height: 844 }
];

describe('Responsive Homepage Tests', () => {
  let page;

  beforeAll(async () => {
    page = await browser.newPage();
  });

  viewports.forEach(viewport => {
    test(`Homepage ${viewport.name}`, async () => {
      await page.setViewport({
        width: viewport.width,
        height: viewport.height
      });

      await page.goto('https://staging.yoursite.com', {
        waitUntil: 'networkidle0'
      });

      const screenshot = await page.screenshot({
        fullPage: true
      });

      expect(screenshot).toMatchImageSnapshot({
        customSnapshotIdentifier: `homepage-${viewport.name.toLowerCase()}`,
        failureThreshold: 0.01,
        failureThresholdType: 'percent'
      });
    });
  });
});

Test Dark Mode vs Light Mode

test('Homepage Light Mode', async () => {
  await page.goto('https://staging.yoursite.com', {
    waitUntil: 'networkidle0'
  });

  // Ensure light mode active
  await page.evaluate(() => {
    document.body.classList.remove('dark-mode');
  });

  const screenshot = await page.screenshot({ fullPage: true });

  expect(screenshot).toMatchImageSnapshot({
    customSnapshotIdentifier: 'homepage-light-mode'
  });
});

test('Homepage Dark Mode', async () => {
  await page.goto('https://staging.yoursite.com', {
    waitUntil: 'networkidle0'
  });

  // Activate dark mode
  await page.evaluate(() => {
    document.body.classList.add('dark-mode');
  });

  const screenshot = await page.screenshot({ fullPage: true });

  expect(screenshot).toMatchImageSnapshot({
    customSnapshotIdentifier: 'homepage-dark-mode'
  });
});

Test Logged-In User Views

test('User Dashboard Logged In', async () => {
  // Login first
  await page.goto('https://staging.yoursite.com/wp-login.php');

  await page.type('#user_login', 'testuser');
  await page.type('#user_pass', 'testpassword');
  await page.click('#wp-submit');

  await page.waitForNavigation({ waitUntil: 'networkidle0' });

  // Navigate to dashboard
  await page.goto('https://staging.yoursite.com/my-account/', {
    waitUntil: 'networkidle0'
  });

  const screenshot = await page.screenshot({ fullPage: true });

  expect(screenshot).toMatchImageSnapshot({
    customSnapshotIdentifier: 'user-dashboard-logged-in',
    failureThreshold: 0.02,
    failureThresholdType: 'percent'
  });
});

CI/CD Integration

GitHub Actions Workflow

.github/workflows/visual-tests.yml:

name: Visual Regression Tests

on:
  pull_request:
    branches:
      - main
      - develop

jobs:
  visual-tests:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm install

      - name: Run visual tests
        run: npm test

      - name: Upload diff images on failure
        if: failure()
        uses: actions/upload-artifact@v3
        with:
          name: visual-test-diffs
          path: __diff_output__/

      - name: Comment PR with results
        if: failure()
        uses: actions/github-script@v6
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '⚠️ Visual regression tests failed! Check artifacts for diff images.'
            })

Now:

Developer creates PR
GitHub Actions runs visual tests automatically
Tests fail if layout changes detected
Blocks merge until visual regressions fixed!!

For more on WordPress theme performance testing, see my article on Why Your Avada Theme Site Fails Core Web Vitals.

Handling Dynamic Content

Problem: Timestamps Break Tests

// WRONG - timestamps cause false failures
test('Blog Archive', async () => {
  await page.goto('https://staging.yoursite.com/blog/');

  const screenshot = await page.screenshot({ fullPage: true });

  // This will ALWAYS fail because post dates change!!
  expect(screenshot).toMatchImageSnapshot();
});

Solution: Hide Dynamic Elements

test('Blog Archive (Stable)', async () => {
  await page.goto('https://staging.yoursite.com/blog/', {
    waitUntil: 'networkidle0'
  });

  // Hide timestamps before screenshot
  await page.evaluate(() => {
    document.querySelectorAll('.entry-date').forEach(el => {
      el.style.visibility = 'hidden';
    });
  });

  const screenshot = await page.screenshot({ fullPage: true });

  expect(screenshot).toMatchImageSnapshot({
    failureThreshold: 0.01,
    failureThresholdType: 'percent'
  });
});

Alternative: Screenshot Specific Elements

test('Blog Post Card Layout', async () => {
  await page.goto('https://staging.yoursite.com/blog/');

  // Screenshot only first post card (stable structure)
  const element = await page.$('.post-card:first-child .post-card-content');
  const screenshot = await element.screenshot();

  expect(screenshot).toMatchImageSnapshot({
    customSnapshotIdentifier: 'blog-post-card-layout'
  });
});

Real-World Scenario: Theme Update

Client: "We need to update Divi theme from 5.0 to 5.2"

Before automated testing:

Update Divi on staging
Manually check 10 pages
Deploy to production
Mobile navigation completely broken!!
Emergency rollback
Client furious!!

With automated testing:

# Update Divi on staging
# Run visual tests

npm test

# Output:
# FAIL  tests/navigation.test.js
#   ✗ Mobile Navigation (3821ms)
#
# Expected image to match snapshot but was 15.3% different
# Mobile menu button position shifted 50px
#
# See: __diff_output__/navigation-test-js-mobile-nav-1-diff.png

Visual diff shows:

Baseline: Mobile menu button top-right corner
Current: Mobile menu button off-screen
Caught BEFORE production!!

Fix CSS, re-run tests:

npm test

# PASS  tests/navigation.test.js
#   ✓ Mobile Navigation (3654ms)
#
# Snapshots:   1 passed, 1 total

Deploy to production with confidence!!

For comprehensive Divi optimization, check out Divi Speed Optimization: Get 90+ PageSpeed Without Breaking Your Site.

Performance Optimization

Parallel Test Execution

package.json:

{
  "scripts": {
    "test": "jest --maxWorkers=4"
  }
}

Runs 4 tests simultaneously = 4x faster!!

Skip Unnecessary Resources

beforeAll(async () => {
  page = await browser.newPage();

  // Block images for faster tests (layout-only testing)
  await page.setRequestInterception(true);

  page.on('request', request => {
    if (request.resourceType() === 'image') {
      request.abort();
    } else {
      request.continue();
    }
  });
});

20-40% faster test execution!!

Bottom Line

Stop deploying broken layouts to production!!

Automated visual regression testing:

Puppeteer screenshots (50+ pages in minutes)
Jest image comparison (pixel-perfect)
CI/CD integration (blocks bad deploys)
Catches layout breaks BEFORE users see them!!

My agency results:

Before automation:

3 broken deployments per month
2-4 hours emergency fixes each
Client complaints = lost revenue

After automation:

0 broken deployments in 6 months
Visual regressions caught in CI/CD
100% deployment confidence!!

Setup time: 4 hours initial configuration

ROI: First caught regression paid for entire setup!!

For WordPress agencies: Visual regression testing is NON-NEGOTIABLE!!

Compare 1,000 screenshots automatically vs manually checking 20 pages = massive time savings + zero broken deployments!! 📸

This article contains affiliate links!

Improving WordPress Frontend Performance Using Critical CSS and Resource Hints

Martijn Assie — Tue, 03 Feb 2026 22:37:19 +0000

Client complaint: "Your site takes 5 seconds to show anything useful!!"

The problem:

Render-blocking CSS files
Browser waiting for full stylesheet
Blank white screen for 4-5 seconds
Users bouncing before page renders!!

My solution:

Extract critical CSS (above-fold only)
Inline in <head> tag
Add resource hints (preload, prefetch, preconnect)
Content visible in 800ms!!

Here's how to dramatically improve WordPress frontend performance:

The Performance Problem

Typical WordPress site loading:

Browser requests HTML
HTML references style.css (150KB)
Browser downloads entire 150KB CSS file
Browser parses ALL 150KB
Browser finally renders page
User sees content after 4-5 seconds!!

The issue: 90% of that CSS isn't needed for above-the-fold content!!

Above-the-fold = content visible without scrolling

Below-the-fold = everything user has to scroll to see

Why load styles for footer, sidebar, comments when user only sees header and hero section initially???

Solution 1: Critical CSS Extraction

What is Critical CSS?

Critical CSS = minimal CSS required to render above-the-fold content

Example:

Your full style.css:

150KB total
3,200 CSS rules
Styles header, content, sidebar, footer, widgets, comments, forms

Critical CSS (above-fold only):

8KB!!
127 CSS rules
Styles ONLY header, hero section, navigation
95% smaller!!

The Critical CSS Workflow

Step 1: Identify above-fold styles

Chrome DevTools Coverage tool:

1. Open site in Chrome
2. Press F12 (DevTools)
3. Click three dots → More tools → Coverage
4. Click reload button
5. See red (unused) vs green (used) CSS

Red = below-fold, Green = critical!!

Step 2: Extract critical CSS

Manual extraction (tedious):

/* Copy only above-fold styles from Coverage tool */

/* Header styles */
.site-header {
    background: #1a1a1a;
    padding: 20px;
}

.site-logo {
    max-width: 200px;
}

/* Hero section */
.hero-section {
    height: 600px;
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

.hero-title {
    font-size: 48px;
    color: #ffffff;
    font-weight: 700;
}

/* Navigation */
.main-nav ul {
    display: flex;
    gap: 20px;
}

.main-nav a {
    color: #ffffff;
    text-decoration: none;
}

Step 3: Inline critical CSS

Add to functions.php:

<?php
function add_critical_css() {
    ?>
    <style id="critical-css">
        /* Paste critical CSS here */
        .site-header{background:#1a1a1a;padding:20px}
        .site-logo{max-width:200px}
        .hero-section{height:600px;background:linear-gradient(135deg,#667eea 0%,#764ba2 100%)}
        .hero-title{font-size:48px;color:#fff;font-weight:700}
        .main-nav ul{display:flex;gap:20px}
        .main-nav a{color:#fff;text-decoration:none}
    </style>
    <?php
}
add_action('wp_head', 'add_critical_css', 1);

Step 4: Defer full stylesheet

Load main CSS asynchronously:

<?php
function load_css_async() {
    ?>
    <link rel="preload" 
          href="<?php echo get_stylesheet_uri(); ?>" 
          as="style" 
          onload="this.onload=null;this.rel='stylesheet'">
    <noscript>
        <link rel="stylesheet" href="<?php echo get_stylesheet_uri(); ?>">
    </noscript>
    <?php
}
add_action('wp_head', 'load_css_async', 20);

// Remove default stylesheet enqueue
function remove_default_stylesheet() {
    wp_dequeue_style('style');
}
add_action('wp_enqueue_scripts', 'remove_default_stylesheet', 100);

Result:

Browser instantly has critical CSS (inlined in HTML)
Renders above-fold in <1 second
Full stylesheet loads in background
Users see content immediately!!

Solution 2: Resource Hints

Preload (High Priority)

Preload = tell browser to fetch resource IMMEDIATELY

Use for: fonts, hero images, critical JavaScript

Preload Custom Fonts

<?php
function preload_custom_fonts() {
    ?>
    <link rel="preload" 
          href="<?php echo get_template_directory_uri(); ?>/fonts/inter-var.woff2" 
          as="font" 
          type="font/woff2" 
          crossorigin>
    <link rel="preload" 
          href="<?php echo get_template_directory_uri(); ?>/fonts/montserrat-bold.woff2" 
          as="font" 
          type="font/woff2" 
          crossorigin>
    <?php
}
add_action('wp_head', 'preload_custom_fonts', 5);

Important: crossorigin attribute required for fonts!!

Preload Hero Image

<?php
function preload_hero_image() {
    if (is_front_page()) {
        ?>
        <link rel="preload" 
              href="<?php echo get_template_directory_uri(); ?>/images/hero-bg.webp" 
              as="image" 
              fetchpriority="high">
        <?php
    }
}
add_action('wp_head', 'preload_hero_image', 5);

fetchpriority="high" = browser prioritizes this image over others!!

Preload Critical JavaScript

<?php
function preload_critical_js() {
    ?>
    <link rel="preload" 
          href="<?php echo get_template_directory_uri(); ?>/js/main.min.js" 
          as="script">
    <?php
}
add_action('wp_head', 'preload_critical_js', 5);

Preconnect (Early Connections)

Preconnect = establish connection to external domain BEFORE resources requested

Use for: Google Fonts, CDNs, analytics

<?php
function add_preconnect_hints() {
    ?>
    <!-- Google Fonts -->
    <link rel="preconnect" href="https://fonts.googleapis.com">
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>

    <!-- CDN -->
    <link rel="preconnect" href="https://cdn.example.com">

    <!-- Analytics (if critical) -->
    <link rel="preconnect" href="https://www.google-analytics.com">
    <?php
}
add_action('wp_head', 'add_preconnect_hints', 1);

Savings: 500-800ms per connection (DNS + TLS + TCP handshake)!!

Prefetch (Future Pages)

Prefetch = download resources user will PROBABLY need next

Use for: next page in funnel, popular destinations

<?php
function smart_prefetch() {
    // Homepage → About page prefetch
    if (is_front_page()) {
        ?>
        <link rel="prefetch" href="<?php echo home_url('/about/'); ?>">
        <link rel="prefetch" href="<?php echo get_template_directory_uri(); ?>/js/contact-form.js" as="script">
        <?php
    }

    // Blog archive → Likely next page
    if (is_home() || is_archive()) {
        global $wp_query;
        if ($wp_query->max_num_pages > 1) {
            ?>
            <link rel="prefetch" href="<?php echo get_pagenum_link(2); ?>">
            <?php
        }
    }

    // Single product → Cart page prefetch
    if (is_product()) {
        ?>
        <link rel="prefetch" href="<?php echo wc_get_cart_url(); ?>">
        <link rel="prefetch" href="<?php echo get_template_directory_uri(); ?>/js/cart.js" as="script">
        <?php
    }
}
add_action('wp_head', 'smart_prefetch');

Result: Next page loads INSTANTLY from prefetch cache!!

DNS-Prefetch (Lightweight)

DNS-Prefetch = resolve domain name early (doesn't download resource)

Use for: external domains with high latency

<?php
function add_dns_prefetch() {
    ?>
    <link rel="dns-prefetch" href="//www.googletagmanager.com">
    <link rel="dns-prefetch" href="//stats.wp.com">
    <link rel="dns-prefetch" href="//platform.twitter.com">
    <?php
}
add_action('wp_head', 'add_dns_prefetch', 1);

Automated Solution: WP Rocket + Perfmatters

WP Rocket Configuration

Enable Critical CSS:

WP Rocket Dashboard →
File Optimization →
CSS Files →
☑ Optimize CSS delivery →
☑ Remove Unused CSS (recommended)

WP Rocket automatically:

Extracts critical CSS per page type
Inlines critical CSS in <head>
Loads full CSS asynchronously
Zero manual work!!

Perfmatters Configuration

Preload Critical Images:

Perfmatters →
Assets →
Preload →
Add URLs to preload:
- /wp-content/themes/mytheme/images/hero-bg.webp (type: image)
- /wp-content/themes/mytheme/fonts/inter-var.woff2 (type: font)

Resource Hints:

Perfmatters →
Assets →
Preconnect:
- https://fonts.googleapis.com
- https://fonts.gstatic.com

DNS Prefetch:
- //www.googletagmanager.com
- //cdnjs.cloudflare.com

Perfmatters automatically excludes preloaded images from lazy loading!!

Real-World Implementation

Scenario: E-commerce Homepage

Before optimization:

HTML downloaded: 200ms
style.css (180KB) downloaded: 1200ms
style.css parsed: 800ms
Fonts loaded: 600ms
First Contentful Paint: 2800ms
Largest Contentful Paint: 3200ms

After optimization:

<?php
// Critical CSS inline (9KB)
function ecommerce_critical_css() {
    ?>
    <style>
        .site-header{background:#fff;box-shadow:0 2px 4px rgba(0,0,0,.1)}
        .hero-banner{height:500px;background:#f0f0f0}
        .product-grid{display:grid;grid-template-columns:repeat(4,1fr);gap:20px}
        .product-card{background:#fff;padding:15px;border-radius:8px}
    </style>
    <?php
}
add_action('wp_head', 'ecommerce_critical_css', 1);

// Preconnect to payment gateway
function ecommerce_preconnect() {
    ?>
    <link rel="preconnect" href="https://js.stripe.com">
    <link rel="preconnect" href="https://fonts.googleapis.com">
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
    <?php
}
add_action('wp_head', 'ecommerce_preconnect', 2);

// Preload hero image
function ecommerce_preload() {
    ?>
    <link rel="preload" href="<?php echo get_template_directory_uri(); ?>/images/hero-sale.webp" as="image" fetchpriority="high">
    <link rel="preload" href="<?php echo get_template_directory_uri(); ?>/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin>
    <?php
}
add_action('wp_head', 'ecommerce_preload', 3);

// Prefetch cart page (users likely add to cart)
function ecommerce_prefetch() {
    if (is_shop() || is_product()) {
        ?>
        <link rel="prefetch" href="<?php echo wc_get_cart_url(); ?>">
        <?php
    }
}
add_action('wp_head', 'ecommerce_prefetch');

After results:

Critical CSS inline: 0ms (in HTML)
Above-fold renders: 600ms
Full CSS loads async: 1200ms (background)
First Contentful Paint: 600ms (78% faster!!)
Largest Contentful Paint: 900ms (72% faster!!)

Conversion rate increased 23% because users see products faster!!

Advanced: Per-Page Critical CSS

Problem: Homepage critical CSS ≠ single post critical CSS

Solution: Generate separate critical CSS per template

<?php
function template_specific_critical_css() {
    if (is_front_page()) {
        // Homepage critical CSS
        $critical_css = file_get_contents(get_template_directory() . '/css/critical-home.css');
    } elseif (is_single()) {
        // Single post critical CSS
        $critical_css = file_get_contents(get_template_directory() . '/css/critical-single.css');
    } elseif (is_page()) {
        // Page critical CSS
        $critical_css = file_get_contents(get_template_directory() . '/css/critical-page.css');
    } elseif (is_archive()) {
        // Archive critical CSS
        $critical_css = file_get_contents(get_template_directory() . '/css/critical-archive.css');
    } else {
        // Fallback
        $critical_css = file_get_contents(get_template_directory() . '/css/critical-default.css');
    }

    echo '<style id="critical-css">' . $critical_css . '</style>';
}
add_action('wp_head', 'template_specific_critical_css', 1);

Store critical CSS files:

/wp-content/themes/mytheme/css/
├── critical-home.css (12KB)
├── critical-single.css (8KB)
├── critical-page.css (7KB)
├── critical-archive.css (9KB)
└── critical-default.css (10KB)

Monitoring Performance

Chrome DevTools Network Tab

Purple bars = preloaded resources

Check waterfall:

HTML loads
Preconnected domains connect early
Preloaded fonts/images download immediately
Critical CSS inline (no download)
Full CSS loads async in background

Look for: "from preload cache" in Size column!!

PageSpeed Insights

Metrics to watch:

First Contentful Paint: Should drop 60-80%
Largest Contentful Paint: Should drop 50-70%
Speed Index: Should improve 40-60%

Before: FCP 2.8s, LCP 3.2s

After: FCP 0.6s (79% faster!!), LCP 0.9s (72% faster!!)

Real User Monitoring

// Measure actual user metrics
const observer = new PerformanceObserver((list) => {
    for (const entry of list.getEntries()) {
        if (entry.name === 'first-contentful-paint') {
            console.log('FCP:', entry.startTime);
            // Send to analytics
            gtag('event', 'timing_complete', {
                name: 'fcp',
                value: Math.round(entry.startTime)
            });
        }
    }
});

observer.observe({ entryTypes: ['paint'] });

Common Mistakes to Avoid

❌ DON'T preload too many resources

Limit to 2-3 critical assets:

1 font file
1 hero image
1 critical JavaScript file

Preloading 10+ resources clogs network and slows everything!!

❌ DON'T inline huge CSS files

Critical CSS should be <15KB

If larger → you're including below-fold styles!!

❌ DON'T preconnect to 20 domains

Limit to 3-4 most critical external origins:

Google Fonts
CDN
Payment gateway
Analytics (if critical)

❌ DON'T prefetch current page resources

Prefetch = FUTURE navigation only

Don't prefetch resources already on current page!!

✅ DO test on mobile networks

Use Chrome DevTools throttling:

Fast 3G
Slow 3G

Critical CSS shines on slow connections!!

Bottom Line

Stop sending 150KB CSS files for 8KB of above-fold styles!!

The winning combo:

Extract critical CSS (above-fold only)
Inline in <head> tag
Preload critical fonts and hero images
Preconnect to external domains
Defer full CSS (async load)
Prefetch next likely page

My client results:

Before:

FCP: 2.8s
LCP: 3.2s
Bounce rate: 58%

After:

FCP: 0.6s (79% faster!!)
LCP: 0.9s (72% faster!!)
Bounce rate: 35% (40% improvement!!)
Conversion rate up 23%!!

Setup time: 2 hours with WP Rocket + Perfmatters

ROI: Paid for itself in first week from reduced bounce rate!!

For serious performance: Critical CSS + resource hints are NON-NEGOTIABLE!!

Users see content in <1 second instead of 3-5 seconds = massive UX win!! ⚡

This article contains affiliate links!

Automating Global Styling Consistency Across WordPress Sites

Martijn Assie — Tue, 03 Feb 2026 18:23:58 +0000

Agency problem: 25 client sites, brand refresh changes primary color

Manual approach:

Log into 25 WordPress dashboards
Navigate to Customizer on each site
Update colors manually
Check each page
6 hours of clicking!!

My approach:

Update master theme.json file
Run sync script
REST API pushes to all 25 sites
Done in 90 seconds!!

Here's how to automate global styling consistency across multiple WordPress sites:

The Global Styling Problem

Before theme.json:

Custom CSS scattered across themes
Inline styles in Customizer
Plugin-specific style settings
Zero consistency, maximum chaos!!

With theme.json (but manual):

Centralized styling... per site
Still copying styles 50 times
Client changes = manual updates everywhere

With automation:

One source of truth
Push updates to all sites
Consistent branding across network
Change once, update everywhere!!

Architecture: Master Config → REST API → All Sites

Component 1: Master theme.json Repository

GitHub repo structure:

global-styles-master/
├── configs/
│   ├── client-a.json        # Brand A styles
│   ├── client-b.json        # Brand B styles
│   └── default.json         # Fallback
├── scripts/
│   ├── sync.js              # Push to sites
│   ├── validate.js          # Check theme.json
│   └── preview.js           # Test locally
└── package.json

Component 2: REST API Endpoints

WordPress Global Styles REST API:

GET  /wp-json/wp/v2/global-styles/<id>
POST /wp-json/wp/v2/global-styles/<id>

Component 3: Sync Automation

Node.js script pushes styles via REST API to all sites!!

Step 1: Create Master theme.json

client-a.json (Full Configuration)

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "primary",
          "color": "#FF6B35",
          "name": "Primary"
        },
        {
          "slug": "secondary",
          "color": "#004E89",
          "name": "Secondary"
        },
        {
          "slug": "accent",
          "color": "#F7C59F",
          "name": "Accent"
        },
        {
          "slug": "base",
          "color": "#FFFFFF",
          "name": "Base"
        },
        {
          "slug": "contrast",
          "color": "#1A1A1A",
          "name": "Contrast"
        }
      ],
      "gradients": [
        {
          "slug": "primary-to-secondary",
          "gradient": "linear-gradient(135deg, #FF6B35 0%, #004E89 100%)",
          "name": "Primary to Secondary"
        }
      ]
    },
    "typography": {
      "fontFamilies": [
        {
          "fontFamily": "\"Inter\", sans-serif",
          "slug": "body",
          "name": "Body"
        },
        {
          "fontFamily": "\"Montserrat\", sans-serif",
          "slug": "heading",
          "name": "Heading"
        }
      ],
      "fontSizes": [
        {
          "slug": "small",
          "size": "14px",
          "name": "Small"
        },
        {
          "slug": "medium",
          "size": "16px",
          "name": "Medium"
        },
        {
          "slug": "large",
          "size": "24px",
          "name": "Large"
        },
        {
          "slug": "x-large",
          "size": "32px",
          "name": "Extra Large"
        }
      ]
    },
    "spacing": {
      "units": ["px", "em", "rem", "vh", "vw", "%"],
      "spacingSizes": [
        {
          "slug": "small",
          "size": "1rem",
          "name": "Small"
        },
        {
          "slug": "medium",
          "size": "2rem",
          "name": "Medium"
        },
        {
          "slug": "large",
          "size": "4rem",
          "name": "Large"
        }
      ]
    },
    "layout": {
      "contentSize": "800px",
      "wideSize": "1200px"
    }
  },
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--base)",
      "text": "var(--wp--preset--color--contrast)"
    },
    "typography": {
      "fontFamily": "var(--wp--preset--font-family--body)",
      "fontSize": "var(--wp--preset--font-size--medium)",
      "lineHeight": "1.6"
    },
    "elements": {
      "h1": {
        "typography": {
          "fontFamily": "var(--wp--preset--font-family--heading)",
          "fontSize": "var(--wp--preset--font-size--x-large)",
          "fontWeight": "700"
        }
      },
      "h2": {
        "typography": {
          "fontFamily": "var(--wp--preset--font-family--heading)",
          "fontSize": "var(--wp--preset--font-size--large)",
          "fontWeight": "600"
        }
      },
      "link": {
        "color": {
          "text": "var(--wp--preset--color--primary)"
        },
        ":hover": {
          "color": {
            "text": "var(--wp--preset--color--secondary)"
          }
        }
      },
      "button": {
        "color": {
          "background": "var(--wp--preset--color--primary)",
          "text": "var(--wp--preset--color--base)"
        },
        "border": {
          "radius": "4px"
        },
        "typography": {
          "fontWeight": "600"
        }
      }
    }
  }
}

CSS variables automatically generated:

:root {
  --wp--preset--color--primary: #FF6B35;
  --wp--preset--color--secondary: #004E89;
  --wp--preset--font-family--body: "Inter", sans-serif;
  /* ... and 20+ more!! */
}

Use anywhere in theme:

.custom-element {
  color: var(--wp--preset--color--primary);
  font-family: var(--wp--preset--font-family--heading);
}

Step 2: Sync Script (Node.js)

scripts/sync.js

const fs = require('fs');
const axios = require('axios');

// Configuration
const sites = require('../sites.json'); // List of sites
const configFile = process.argv[2] || 'configs/default.json';

console.log(`📦 Loading config: ${configFile}`);
const globalStyles = JSON.parse(fs.readFileSync(configFile, 'utf8'));

async function syncToSite(site) {
    console.log(`\n🔄 Syncing to: ${site.url}`);

    try {
        // Authenticate
        const auth = Buffer.from(`${site.username}:${site.app_password}`).toString('base64');

        // Get current global styles ID
        const stylesResponse = await axios.get(
            `${site.url}/wp-json/wp/v2/global-styles`,
            {
                headers: {
                    'Authorization': `Basic ${auth}`
                }
            }
        );

        if (stylesResponse.data.length === 0) {
            console.log('❌ No global styles found');
            return;
        }

        const globalStylesId = stylesResponse.data[0].id;

        // Update global styles
        const updateResponse = await axios.post(
            `${site.url}/wp-json/wp/v2/global-styles/${globalStylesId}`,
            {
                settings: globalStyles.settings,
                styles: globalStyles.styles
            },
            {
                headers: {
                    'Authorization': `Basic ${auth}`,
                    'Content-Type': 'application/json'
                }
            }
        );

        console.log(`✅ Success! Updated global styles ID ${globalStylesId}`);

        // Optionally clear cache
        if (site.has_cache_plugin) {
            await clearCache(site, auth);
        }

    } catch (error) {
        console.log(`❌ Error: ${error.message}`);
        if (error.response) {
            console.log(`   Response: ${JSON.stringify(error.response.data)}`);
        }
    }
}

async function clearCache(site, auth) {
    try {
        // WP Rocket cache clear
        await axios.post(
            `${site.url}/wp-json/wp-rocket/v1/cache/clear`,
            {},
            {
                headers: { 'Authorization': `Basic ${auth}` }
            }
        );
        console.log('🧹 Cache cleared');
    } catch (error) {
        console.log('⚠️  Cache clear failed (might not be installed)');
    }
}

// Sync to all sites
async function syncAll() {
    console.log(`\n🚀 Syncing to ${sites.length} sites...\n`);

    for (const site of sites) {
        await syncToSite(site);
        // Rate limit - wait 1 second between sites
        await new Promise(resolve => setTimeout(resolve, 1000));
    }

    console.log('\n✨ Sync complete!\n');
}

syncAll();

sites.json (Site List)

[
  {
    "url": "https://clienta.com",
    "username": "admin",
    "app_password": "xxxx xxxx xxxx xxxx xxxx xxxx",
    "has_cache_plugin": true
  },
  {
    "url": "https://clientb.com",
    "username": "admin",
    "app_password": "yyyy yyyy yyyy yyyy yyyy yyyy",
    "has_cache_plugin": true
  },
  {
    "url": "https://clientc.com",
    "username": "admin",
    "app_password": "zzzz zzzz zzzz zzzz zzzz zzzz",
    "has_cache_plugin": false
  }
]

Generate Application Passwords:

WordPress Dashboard → Users → Profile → Application Passwords

Create new password for "Global Styles Sync"

Step 3: Run Sync

# Install dependencies
npm install axios

# Sync default config to all sites
node scripts/sync.js configs/default.json

# Output:
# 📦 Loading config: configs/default.json
# 🚀 Syncing to 3 sites...
# 
# 🔄 Syncing to: https://clienta.com
# ✅ Success! Updated global styles ID 42
# 🧹 Cache cleared
# 
# 🔄 Syncing to: https://clientb.com
# ✅ Success! Updated global styles ID 38
# 🧹 Cache cleared
# 
# 🔄 Syncing to: https://clientc.com
# ✅ Success! Updated global styles ID 51
# 
# ✨ Sync complete!

25 sites updated in 90 seconds!!

Step 4: WordPress Multisite Automation

For Multisite Networks

Different approach - direct database access:

<?php
/**
 * Plugin Name: Global Styles Multisite Sync
 * Description: Sync global styles across multisite network
 */

add_action('admin_menu', 'gss_add_admin_menu');

function gss_add_admin_menu() {
    if (!is_super_admin()) {
        return;
    }

    add_submenu_page(
        'network/settings.php',
        'Global Styles Sync',
        'Global Styles Sync',
        'manage_network',
        'global-styles-sync',
        'gss_admin_page'
    );
}

function gss_admin_page() {
    if (isset($_POST['sync_styles'])) {
        gss_sync_to_all_sites();
    }

    ?>
    <div class="wrap">
        <h1>Global Styles Multisite Sync</h1>

        <form method="post">
            <h2>Master Global Styles (JSON)</h2>
            <textarea name="global_styles" rows="20" cols="100"><?php
                echo esc_textarea(get_site_option('gss_master_styles', ''));
            ?></textarea>

            <p>
                <button type="submit" name="sync_styles" class="button button-primary">
                    Sync to All Sites in Network
                </button>
            </p>
        </form>
    </div>
    <?php
}

function gss_sync_to_all_sites() {
    $master_styles = json_decode($_POST['global_styles'], true);

    if (!$master_styles) {
        wp_die('Invalid JSON');
    }

    // Save master config
    update_site_option('gss_master_styles', $_POST['global_styles']);

    // Get all sites in network
    $sites = get_sites(['number' => 999]);

    $synced = 0;

    foreach ($sites as $site) {
        switch_to_blog($site->blog_id);

        // Find global styles post for current theme
        $theme_slug = get_stylesheet();

        $global_styles_query = new WP_Query([
            'post_type' => 'wp_global_styles',
            'post_status' => 'publish',
            'posts_per_page' => 1,
            'no_found_rows' => true,
            'meta_query' => [
                [
                    'key' => 'theme',
                    'value' => $theme_slug
                ]
            ]
        ]);

        if ($global_styles_query->have_posts()) {
            $global_styles_post = $global_styles_query->posts[0];

            // Update post content with new styles
            wp_update_post([
                'ID' => $global_styles_post->ID,
                'post_content' => wp_json_encode([
                    'version' => 2,
                    'isGlobalStylesUserThemeJSON' => true,
                    'settings' => $master_styles['settings'],
                    'styles' => $master_styles['styles']
                ])
            ]);

            $synced++;
        }

        restore_current_blog();
    }

    echo "<div class='notice notice-success'><p>✅ Synced to {$synced} sites!</p></div>";
}

Step 5: Validation & Preview

Validate theme.json

// scripts/validate.js
const Ajv = require('ajv');
const fs = require('fs');

const ajv = new Ajv();

// Fetch WordPress theme.json schema
const schema = require('./wp-theme-json-schema.json'); // Download from WordPress.org

const configFile = process.argv[2];
const config = JSON.parse(fs.readFileSync(configFile, 'utf8'));

const validate = ajv.compile(schema);
const valid = validate(config);

if (valid) {
    console.log('✅ Valid theme.json!');
} else {
    console.log('❌ Invalid theme.json:');
    console.log(validate.errors);
    process.exit(1);
}

Preview Locally

# Copy to local WordPress theme
cp configs/client-a.json ~/Local\ Sites/test-site/app/public/wp-content/themes/my-theme/theme.json

# Refresh WordPress admin
# Check Appearance → Editor → Styles

Step 6: CI/CD Integration

GitHub Actions Workflow

.github/workflows/sync-styles.yml:

name: Sync Global Styles

on:
  push:
    branches:
      - main
    paths:
      - 'configs/*.json'
  workflow_dispatch:
    inputs:
      config:
        description: 'Config file to sync'
        required: true

jobs:
  sync:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm install

      - name: Validate theme.json
        run: node scripts/validate.js ${{ github.event.inputs.config || 'configs/default.json' }}

      - name: Sync to sites
        env:
          SITES_CONFIG: ${{ secrets.SITES_JSON }}
        run: |
          echo "$SITES_CONFIG" > sites.json
          node scripts/sync.js ${{ github.event.inputs.config || 'configs/default.json' }}

      - name: Notify Slack
        uses: 8398a7/action-slack@v3
        with:
          status: ${{ job.status }}
          text: '✅ Global styles synced to production'
          webhook_url: ${{ secrets.SLACK_WEBHOOK }}

Now:

Edit configs/client-a.json
Commit and push to GitHub
GitHub Actions automatically syncs to all sites!!

Real-World Scenarios

Scenario 1: Brand Color Refresh

Client: "Change primary color from #FF6B35 to #E63946"

Old way:

Log into 25 sites
Update Customizer on each
6 hours

New way:

# Edit configs/client-a.json
sed -i 's/#FF6B35/#E63946/g' configs/client-a.json

# Sync
node scripts/sync.js configs/client-a.json

# Done in 90 seconds!!

Scenario 2: Typography Update

Client: "Switch heading font from Montserrat to Raleway"

{
  "fontFamilies": [
    {
      "fontFamily": "\"Raleway\", sans-serif",
      "slug": "heading",
      "name": "Heading"
    }
  ]
}

Sync to all sites:

node scripts/sync.js configs/client-a.json

All 25 sites now use Raleway!!

Scenario 3: Add New Color

{
  "palette": [
    // existing colors...
    {
      "slug": "success",
      "color": "#10B981",
      "name": "Success"
    }
  ]
}

Sync → success color available in block editor on all sites!!

Advanced: Per-Site Overrides

Some sites need slight variations:

// In sync.js
const siteOverrides = {
  'clienta.com': {
    'settings.color.palette[0].color': '#FF0000' // Different primary
  }
};

function applyOverrides(styles, siteUrl) {
    const overrides = siteOverrides[siteUrl];

    if (overrides) {
        for (const [path, value] of Object.entries(overrides)) {
            setNestedValue(styles, path, value);
        }
    }

    return styles;
}

Monitoring & Rollback

Check Sync Status

// scripts/check-status.js
async function checkAllSites() {
    for (const site of sites) {
        const response = await axios.get(
            `${site.url}/wp-json/wp/v2/global-styles`,
            { headers: { 'Authorization': `Basic ${auth}` } }
        );

        const currentPrimary = response.data[0].settings.color.palette
            .find(c => c.slug === 'primary').color;

        console.log(`${site.url}: Primary = ${currentPrimary}`);
    }
}

Rollback

Git makes rollback easy:

# Revert to previous commit
git revert HEAD

# Sync old config
node scripts/sync.js configs/client-a.json

Bottom Line

Stop manually updating styles across multiple sites!!

Automation wins:

One source of truth (theme.json)
REST API syncs to all sites
Brand changes in seconds not hours
Version control with Git
Update 50 sites in 2 minutes!!

My agency:

32 client sites
Brand refresh used to take 2 days
Now takes 5 minutes
Client thinks we're wizards!!

Setup time: 3 hours to build sync system

ROI: Pays for itself on first multi-site brand update!!

For agencies managing multiple sites: This automation is ESSENTIAL!!

Global styles + REST API + automation = styling consistency at scale!! 🎨

This article contains affiliate links!

Creating Reusable WordPress Child Theme Templates With CI/CD

Martijn Assie — Tue, 03 Feb 2026 18:14:05 +0000

Client asks: "Can you build us 5 sites with Astra but different customizations?"

Manual approach: Copy child theme 5 times, modify each one, FTP upload, repeat

Time: 6 hours × 5 sites = 30 hours!!

My approach:

Create reusable child theme template (once!)
GitHub repo with config JSON
GitHub Actions auto-deploys on push
5 sites deployed in 20 minutes!!

Here's how to build reusable child theme templates with CI/CD automation:

Why Reusable Child Theme Templates?

Problem with manual child themes:

Copy/paste same code structure every project
Lose track of which site has which features
Manual FTP uploads (error-prone!)
Client wants changes across all sites = manual work on 10 sites!!
Zero consistency!!

Solution: Template system + CI/CD

One master template
Config-driven customizations
Git tracks everything
Push code → auto-deploys to all sites
Update 50 sites in 2 minutes!!

Architecture Overview

Three components:

1. Base Child Theme Template (GitHub repo)

my-child-theme-template/
├── .github/
│   └── workflows/
│       └── deploy.yml          # GitHub Actions
├── config/
│   ├── default.json           # Default settings
│   ├── client-a.json          # Client A config
│   └── client-b.json          # Client B config
├── src/
│   ├── functions.php
│   ├── style.css
│   └── templates/
├── gulpfile.js                # Build process
└── package.json

2. Configuration System

JSON defines per-client customizations:

{
  "theme_name": "Client A Child",
  "parent_theme": "astra",
  "color_scheme": {
    "primary": "#FF6B35",
    "secondary": "#004E89"
  },
  "features": {
    "custom_post_types": true,
    "woocommerce": false,
    "contact_form": true
  },
  "deploy": {
    "host": "clienta.com",
    "path": "/wp-content/themes/clienta-child"
  }
}

3. GitHub Actions CI/CD

Automatically builds and deploys on push!!

Step 1: Create Base Child Theme Template

Directory Structure

mkdir my-astra-child-template
cd my-astra-child-template
git init

style.css (Template)

/*
Theme Name: {{THEME_NAME}}
Template: {{PARENT_THEME}}
Author: Your Agency
Version: 1.0.0
*/

:root {
  --primary-color: {{PRIMARY_COLOR}};
  --secondary-color: {{SECONDARY_COLOR}};
}

/* Your custom styles */

Placeholders replaced by build process!!

functions.php (Template)

<?php
/**
 * Child Theme Functions
 * Generated from template
 */

// Theme setup
add_action('after_setup_theme', 'child_theme_setup');
function child_theme_setup() {
    // Load config
    $config = json_decode(file_get_contents(__DIR__ . '/config.json'), true);

    // Enqueue styles
    add_action('wp_enqueue_scripts', 'child_theme_enqueue_styles');

    // Conditional features
    if ($config['features']['custom_post_types']) {
        require_once __DIR__ . '/inc/custom-post-types.php';
    }

    if ($config['features']['woocommerce']) {
        require_once __DIR__ . '/inc/woocommerce.php';
    }
}

function child_theme_enqueue_styles() {
    wp_enqueue_style('parent-style', get_template_directory_uri() . '/style.css');
    wp_enqueue_style('child-style', get_stylesheet_uri(), ['parent-style']);
}

package.json

{
  "name": "astra-child-template",
  "version": "1.0.0",
  "scripts": {
    "build": "node build.js",
    "deploy": "npm run build && npm run upload"
  },
  "devDependencies": {
    "replace-in-file": "^6.3.5",
    "archiver": "^5.3.1"
  }
}

Step 2: Build Script (Placeholder Replacement)

build.js

const fs = require('fs');
const path = require('path');
const replace = require('replace-in-file');
const archiver = require('archiver');

// Load config
const configFile = process.env.CONFIG_FILE || 'config/default.json';
const config = JSON.parse(fs.readFileSync(configFile, 'utf8'));

console.log(`Building for: ${config.theme_name}`);

// Create build directory
const buildDir = 'build';
if (!fs.existsSync(buildDir)) {
    fs.mkdirSync(buildDir);
}

// Copy source files
const themeDir = `${buildDir}/${config.slug}`;
fs.cpSync('src', themeDir, { recursive: true });

// Replace placeholders in all files
const replacements = [
    {
        files: `${themeDir}/**/*`,
        from: /{{THEME_NAME}}/g,
        to: config.theme_name
    },
    {
        files: `${themeDir}/**/*`,
        from: /{{PARENT_THEME}}/g,
        to: config.parent_theme
    },
    {
        files: `${themeDir}/**/*`,
        from: /{{PRIMARY_COLOR}}/g,
        to: config.color_scheme.primary
    },
    {
        files: `${themeDir}/**/*`,
        from: /{{SECONDARY_COLOR}}/g,
        to: config.color_scheme.secondary
    }
];

try {
    replacements.forEach(replacement => {
        replace.sync(replacement);
    });
    console.log('✅ Placeholders replaced');
} catch (error) {
    console.error('❌ Error replacing placeholders:', error);
    process.exit(1);
}

// Copy config.json to theme
fs.copyFileSync(configFile, `${themeDir}/config.json`);

// Create ZIP file
const output = fs.createWriteStream(`${buildDir}/${config.slug}.zip`);
const archive = archiver('zip', { zlib: { level: 9 } });

output.on('close', () => {
    console.log(`✅ Created ${config.slug}.zip (${archive.pointer()} bytes)`);
});

archive.on('error', (err) => {
    throw err;
});

archive.pipe(output);
archive.directory(themeDir, config.slug);
archive.finalize();

Run: CONFIG_FILE=config/client-a.json npm run build

Output: build/client-a-child.zip

Step 3: GitHub Actions Workflow

.github/workflows/deploy.yml

name: Deploy Child Theme

on:
  push:
    branches:
      - main
      - staging
  workflow_dispatch:
    inputs:
      config:
        description: 'Config file to deploy'
        required: true
        type: choice
        options:
          - config/client-a.json
          - config/client-b.json
          - config/client-c.json

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        config: 
          - config/client-a.json
          - config/client-b.json

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm install

      - name: Build theme
        run: CONFIG_FILE=${{ matrix.config }} npm run build

      - name: Load config
        id: config
        run: |
          CONFIG=$(cat ${{ matrix.config }})
          echo "host=$(echo $CONFIG | jq -r '.deploy.host')" >> $GITHUB_OUTPUT
          echo "path=$(echo $CONFIG | jq -r '.deploy.path')" >> $GITHUB_OUTPUT
          echo "slug=$(echo $CONFIG | jq -r '.slug')" >> $GITHUB_OUTPUT

      - name: Deploy via SFTP
        uses: SamKirkland/FTP-Deploy-Action@4.3.3
        with:
          server: ${{ steps.config.outputs.host }}
          username: ${{ secrets.FTP_USERNAME }}
          password: ${{ secrets.FTP_PASSWORD }}
          local-dir: ./build/${{ steps.config.outputs.slug }}/
          server-dir: ${{ steps.config.outputs.path }}/
          dangerous-clean-slate: false

      - name: Clear WordPress cache
        uses: appleboy/ssh-action@master
        with:
          host: ${{ steps.config.outputs.host }}
          username: ${{ secrets.SSH_USERNAME }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            cd /var/www/html
            wp cache flush --allow-root

      - name: Notify Slack
        if: success()
        uses: 8398a7/action-slack@v3
        with:
          status: ${{ job.status }}
          text: '✅ Deployed ${{ steps.config.outputs.slug }} to ${{ steps.config.outputs.host }}'
          webhook_url: ${{ secrets.SLACK_WEBHOOK }}

GitHub Secrets Configuration

Settings → Secrets and variables → Actions:

FTP_USERNAME: your-ftp-user
FTP_PASSWORD: your-ftp-password
SSH_USERNAME: your-ssh-user
SSH_PRIVATE_KEY: your-private-key
SLACK_WEBHOOK: your-slack-webhook-url

Step 4: Multi-Client Configuration

config/client-a.json

{
  "theme_name": "Client A Child Theme",
  "slug": "client-a-child",
  "parent_theme": "astra",
  "color_scheme": {
    "primary": "#FF6B35",
    "secondary": "#004E89",
    "accent": "#F7C59F"
  },
  "typography": {
    "heading_font": "Montserrat",
    "body_font": "Open Sans"
  },
  "features": {
    "custom_post_types": true,
    "woocommerce": true,
    "contact_form": true,
    "custom_widgets": false
  },
  "deploy": {
    "host": "clienta.example.com",
    "path": "/public_html/wp-content/themes/client-a-child"
  }
}

config/client-b.json

{
  "theme_name": "Client B Child Theme",
  "slug": "client-b-child",
  "parent_theme": "astra",
  "color_scheme": {
    "primary": "#1A535C",
    "secondary": "#FF6B6B",
    "accent": "#FFE66D"
  },
  "features": {
    "custom_post_types": false,
    "woocommerce": false,
    "contact_form": true,
    "custom_widgets": true
  },
  "deploy": {
    "host": "clientb.example.com",
    "path": "/public_html/wp-content/themes/client-b-child"
  }
}

Step 5: Advanced Features

Conditional File Inclusion

build.js enhancement:

// Remove files based on config
if (!config.features.woocommerce) {
    // Delete WooCommerce files
    const wooFiles = [
        `${themeDir}/inc/woocommerce.php`,
        `${themeDir}/woocommerce/`
    ];
    wooFiles.forEach(file => {
        if (fs.existsSync(file)) {
            fs.rmSync(file, { recursive: true });
            console.log(`Removed: ${file}`);
        }
    });
}

if (!config.features.custom_post_types) {
    fs.rmSync(`${themeDir}/inc/custom-post-types.php`);
}

Version Tracking

Automatic version bumping:

// In build.js
const version = config.version || '1.0.0';
const newVersion = bumpVersion(version); // 1.0.0 → 1.0.1

// Update style.css
replace.sync({
    files: `${themeDir}/style.css`,
    from: /Version: .*/,
    to: `Version: ${newVersion}`
});

// Update config
config.version = newVersion;
fs.writeFileSync(configFile, JSON.stringify(config, null, 2));

Database Migration Scripts

migrations/001_initial_setup.php:

<?php
/**
 * Initial setup migration
 * Runs on theme activation
 */
add_action('after_switch_theme', 'child_theme_migration_001');

function child_theme_migration_001() {
    // Check if already run
    if (get_option('child_theme_migration_001')) {
        return;
    }

    // Load config
    $config = json_decode(file_get_contents(__DIR__ . '/../config.json'), true);

    // Set theme options
    set_theme_mod('primary_color', $config['color_scheme']['primary']);
    set_theme_mod('secondary_color', $config['color_scheme']['secondary']);

    // Create pages if needed
    if ($config['features']['contact_form']) {
        wp_insert_post([
            'post_title' => 'Contact',
            'post_type' => 'page',
            'post_status' => 'publish'
        ]);
    }

    // Mark as run
    update_option('child_theme_migration_001', true);
}

Real-World Workflow

Scenario: Update All Client Sites

Bug fix in custom function:

Fix code in src/functions.php
Commit and push to GitHub

git add src/functions.php
git commit -m "Fix: Custom menu walker bug"
git push origin main

GitHub Actions automatically:
- Builds for Client A
- Builds for Client B
- Builds for Client C
- Deploys all 3 sites
- Clears WordPress cache
- Sends Slack notification

Total time: 2 minutes for 3 sites!!

Scenario: New Client Onboarding

Client D wants Astra child theme:

Create config/client-d.json

{
  "theme_name": "Client D Child",
  "slug": "client-d-child",
  "parent_theme": "astra",
  "color_scheme": {
    "primary": "#6C5CE7",
    "secondary": "#A29BFE"
  },
  "features": {
    "custom_post_types": true,
    "woocommerce": true,
    "contact_form": true
  },
  "deploy": {
    "host": "clientd.example.com",
    "path": "/public_html/wp-content/themes/client-d-child"
  }
}

Update deploy.yml matrix:

strategy:
  matrix:
    config:
      - config/client-a.json
      - config/client-b.json
      - config/client-c.json
      - config/client-d.json  # ADD THIS

Push changes

git add config/client-d.json .github/workflows/deploy.yml
git commit -m "Add Client D configuration"
git push origin main

Client D site deployed automatically!!

Manual Deployment Option

For emergencies or testing:

# Build specific config
CONFIG_FILE=config/client-a.json npm run build

# Output: build/client-a-child.zip

# Upload manually or:
scp build/client-a-child.zip user@clienta.com:/tmp/
ssh user@clienta.com
cd /public_html/wp-content/themes
unzip /tmp/client-a-child.zip
wp cache flush

Testing Before Deployment

Local Testing

# Build for staging
CONFIG_FILE=config/client-a-staging.json npm run build

# Copy to local WordPress
cp -r build/client-a-child ~/Local\ Sites/test-site/app/public/wp-content/themes/

# Test locally, then deploy to production

Staging Environment

Two configs per client:

config/
├── client-a.json           # Production
├── client-a-staging.json   # Staging

Workflow:

Push to staging branch → deploys to staging
Test on staging
Merge to main → deploys to production

Monitoring & Rollback

Version Tags

# After successful deployment
git tag -a v1.2.3 -m "Client A deployment"
git push origin v1.2.3

Rollback Process

# .github/workflows/rollback.yml
name: Rollback Theme

on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to rollback to'
        required: true
      config:
        description: 'Client config'
        required: true

jobs:
  rollback:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout specific version
        uses: actions/checkout@v3
        with:
          ref: ${{ inputs.version }}

      - name: Build and deploy
        # ... same as deploy.yml

Bottom Line

Stop copying child themes manually!!

Reusable template system wins:

Build once, deploy everywhere
Config-driven customizations
Git tracks all changes
Push code = auto-deploy
Update 50 sites in minutes
Zero FTP uploads!!

My agency workflow:

1 base template
27 active clients
Push update → all 27 sites deployed in 5 minutes
Before: 27 × 10 minutes = 4.5 hours per update!!

Setup time: 4 hours to build template + CI/CD

ROI: Pays for itself after 3 multi-site updates!!

For agencies managing multiple client sites: This is NON-NEGOTIABLE!!

CI/CD + child theme templates = agency superpower!! 🚀

This article contains affiliate links!

Debugging WordPress PHP Callbacks With Xdebug

Martijn Assie — Tue, 03 Feb 2026 00:38:45 +0000

Problem: Hook fires, callback runs, something breaks

Error log: Fatal error on line 42

Line 42: return apply_filters('some_filter', $value);

Me staring at code: "Which of these 8 callbacks is causing this?!?"

Before Xdebug:

Add var_dump() everywhere
Reload page 50 times
Still guessing
4 hours wasted!!

After Xdebug:

Set breakpoint on line 42
Step INTO filter callbacks
See exact callback causing issue
Fixed in 10 minutes!!

Here's how to debug WordPress PHP callbacks like a pro using Xdebug:

Why Xdebug For WordPress Callbacks?

WordPress = hook-based architecture

add_action('save_post', 'my_callback', 10);
add_filter('the_content', 'another_callback', 20);
add_action('wp_head', 'third_callback', 5);

Problem:

10 plugins hooking same action
Which callback is breaking?
Can't see execution order
var_dump() only shows ONE callback!!

Xdebug solution:

Set breakpoint on hook
Step through EACH callback
Inspect variables at each step
See call stack
No more guessing!!

Setup: Local + VS Code + Xdebug

Prerequisites

Install:

Local by Flywheel (includes Xdebug built-in!)
VS Code
PHP Debug extension for VS Code

Local download: https://localwp.com/

Step 1: Enable Xdebug in Local

Open Local → Select your site → Bottom of page:

Toggle Xdebug ON

That's it!! Local handles all php.ini configuration!!

Verify Xdebug is running:

Create /wp-content/xdebug-test.php:

<?php
phpinfo();

Visit: yoursite.local/wp-content/xdebug-test.php

Search for "Xdebug" section → should show:

xdebug support: enabled
Version: 3.x

Step 2: Install PHP Debug Extension in VS Code

VS Code → Extensions → Search "PHP Debug"

Install: PHP Debug (by Xdebug)

Step 3: Configure VS Code

Open your site folder in VS Code

Click Debug icon (sidebar) → Create launch.json:

File: .vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/app/public": "${workspaceRoot}"
      },
      "log": false
    }
  ]
}

Key settings:

port: 9003 - Xdebug 3.x uses port 9003 (Xdebug 2.x used 9000)

pathMappings - Maps Local's internal path to your workspace

Step 4: Install Xdebug Browser Extension

Chrome: Xdebug Helper

Firefox: Xdebug Helper

Enable debugging:

Click extension icon
Select "Debug"
Icon turns green ✅

This tells browser to send XDEBUG_SESSION cookie!!

Debugging WordPress Hooks

Example 1: Debug save_post Callbacks

Scenario: Post saves slowly, need to find which callback is slow

Code: wp-content/plugins/my-plugin/my-plugin.php

<?php
add_action('save_post', 'my_slow_callback', 10, 2);

function my_slow_callback($post_id, $post) {
    // Set breakpoint HERE ↓
    $data = get_post_meta($post_id, 'some_key', true);

    // Slow API call
    $result = wp_remote_get('https://api.example.com/data');

    if (is_wp_error($result)) {
        return;
    }

    update_post_meta($post_id, 'api_data', $result['body']);
}

Steps:

Click left of line number to set breakpoint (red dot appears)
VS Code → Debug panel → Click green play "Listen for Xdebug" (F5)
Browser → Edit any post → Click "Update"
VS Code highlights breakpoint line!!

Now you can:

Inspect variables:

Hover over $post_id → see value
Hover over $data → see what was retrieved
Expand arrays/objects

Step through code:

F10: Step Over (run line, don't enter functions)
F11: Step Into (enter function calls)
Shift+F11: Step Out (exit current function)

Check call stack:

See entire execution path
Trace back to what triggered this callback

Example 2: Multiple Callbacks on Same Hook

Problem: 5 plugins all hooking the_content, one breaks

Code:

<?php
// Plugin A
add_filter('the_content', 'plugin_a_content', 10);

// Plugin B
add_filter('the_content', 'plugin_b_content', 20);

// Plugin C
add_filter('the_content', 'plugin_c_content', 30);

Debug strategy:

Set breakpoint in WordPress core where filter fires:

File: wp-includes/plugin.php

Find apply_filters() function:

<?php
public function apply_filters($value, $args) {
    // Set breakpoint HERE ↓
    foreach ($this->callbacks as $priority => $callbacks) {
        foreach ($callbacks as $callback) {
            // Step INTO to see each callback
            $value = call_user_func_array($callback['function'], $args);
        }
    }
    return $value;
}

Now:

F11 (Step Into) on call_user_func_array()
Debugger jumps to actual callback function
Inspect variables
Continue to next callback
Find exact callback causing issue!!

Example 3: Debugging AJAX Callbacks

Problem: AJAX request returns error, can't see why

Code:

<?php
add_action('wp_ajax_my_action', 'my_ajax_callback');
add_action('wp_ajax_nopriv_my_action', 'my_ajax_callback');

function my_ajax_callback() {
    // Set breakpoint HERE ↓
    $post_id = $_POST['post_id'];

    if (!$post_id) {
        wp_send_json_error('Missing post ID');
    }

    $data = get_post($post_id);

    wp_send_json_success($data);
}

Trigger AJAX in browser console:

jQuery.post(ajaxurl, {
    action: 'my_action',
    post_id: 123
});

Debugger stops on breakpoint!!

Inspect:

$_POST array
$post_id value
$data content

Common AJAX issues found:

$_POST empty (missing data in JS)
Wrong variable types
Database queries failing
Permission checks failing

Advanced: Conditional Breakpoints

Problem: Hook fires 100 times, only want to debug when $post_id == 456

Solution: Right-click breakpoint → Edit Breakpoint → Add condition

Condition:

$post_id == 456

Now debugger only stops when condition is TRUE!!

Other useful conditions:

// Only debug for specific user
get_current_user_id() == 1

// Only debug for specific post type
$post->post_type == 'product'

// Only debug when variable is empty
empty($data)

// Only debug on error
is_wp_error($result)

Debugging Hooks Execution Order

Problem: Callbacks running in wrong order

Use: Query Monitor + Xdebug combo

Install Query Monitor plugin

Query Monitor shows all hooks and priorities:

Hook: save_post
  - my_callback (priority 10)
  - another_callback (priority 20)
  - third_callback (priority 5) ← runs FIRST!

Then:

Set breakpoint in each callback

See execution order in real-time!!

Common WordPress Debugging Scenarios

Scenario 1: Filter Returns NULL

Problem:

add_filter('the_title', 'my_title_filter');

function my_title_filter($title) {
    // Forgot to return!!
    $title = strtoupper($title);
}

Without Xdebug: All titles disappear, WTF?!

With Xdebug:

Set breakpoint on $title = strtoupper($title);
Step Over (F10)
See function ends without return
Instant diagnosis!!

Fix:

function my_title_filter($title) {
    $title = strtoupper($title);
    return $title; // ← ADD THIS!!
}

Scenario 2: Hook Priority Conflict

Code:

// Theme
add_action('init', 'theme_setup', 10);

// Plugin
add_action('init', 'plugin_setup', 10); // Same priority!!

Problem: Execution order undefined when priority is same

Debug:

Set breakpoint in both functions

See which runs first

Fix: Change priority

add_action('init', 'plugin_setup', 5); // Run before theme

Scenario 3: Callback Receives Wrong Arguments

Problem:

add_action('save_post', 'my_callback');

function my_callback($post_id) {
    // Missing $post parameter!!
    var_dump($post); // Undefined variable
}

Xdebug shows:

Function only receives 1 argument but hook passes 3:

do_action('save_post', $post_id, $post, $update);

Fix:

add_action('save_post', 'my_callback', 10, 3); // Accept 3 args!!

function my_callback($post_id, $post, $update) {
    // Now we have all arguments
}

VS Code Debugging Panel Explained

When breakpoint hits:

Variables section:

Locals: Current function variables
Superglobals: $_GET, $_POST, $_SERVER, etc.
Constants: WP_DEBUG, ABSPATH, etc.

Watch section:

Add custom expressions
Example: $post->post_status
Updates in real-time as you step through

Call Stack section:

Shows execution path
Click any frame to see that context
Trace back to original trigger

Breakpoints section:

All breakpoints listed
Toggle on/off
Conditional breakpoints marked

Debug Console:

Run PHP expressions
Example: get_option('siteurl')
Evaluate during execution

Troubleshooting Xdebug

Breakpoints Not Hitting

Check:

Xdebug enabled in Local? (toggle ON)
Browser extension enabled? (green icon)
VS Code listening? (F5 pressed)
Port correct in launch.json? (9003 for Xdebug 3.x)

Verify connection:

Add to wp-config.php:

<?php
if (function_exists('xdebug_info')) {
    error_log('Xdebug is loaded!');
}

Check error log → should see message

Path Mapping Issues

Problem: Breakpoints show as "unverified" (gray circle)

Cause: Path mismatch between Local and VS Code

Fix: Update pathMappings in launch.json

Local's internal path: /app/public

Your workspace: /Users/you/Local Sites/yoursite/app/public

Mapping:

"pathMappings": {
  "/app/public": "${workspaceRoot}"
}

Test: Click breakpoint, should turn red

Performance Impact

Xdebug slows down PHP execution

Solution: Only enable when debugging

Local makes this easy → toggle ON/OFF

Pro tip: Use conditional breakpoints to reduce overhead

Bottom Line

Stop using var_dump() for WordPress debugging!!

Xdebug shows:

Exact callback causing issue
Variable values at each step
Execution order
Call stack
Everything you need to fix bugs FAST!!

My debugging time:

Before Xdebug:

Simple bug: 30 minutes
Complex hook issue: 4 hours
"WTF is happening?!" moments: Daily

After Xdebug:

Simple bug: 5 minutes
Complex hook issue: 30 minutes
"WTF is happening?!" moments: GONE!!

Setup time: 10 minutes

Time saved: HUNDREDS of hours

Xdebug = WordPress developer superpower!! 🔥

This article contains affiliate links!

WordPress Page Builder Automation: Generate Layouts via Scripts

Martijn Assie — Tue, 03 Feb 2026 00:25:47 +0000

Client wants: 50 landing pages with same layout, different cities

Manual method: 50 × 15 minutes = 12.5 hours clicking in Elementor!!

My response: "Give me 45 minutes to write a script"

Result:

Script runs: 3 minutes
50 pages created: Identical layouts, unique content
JSON config drives everything
Zero clicking!!

Here's how to automate page builder layout generation programmatically:

Why Automate Page Builder Layouts?

Manual page building SUCKS when:

Creating 50+ similar pages (locations, products, services)
Client wants consistent layouts across all pages
Content changes frequently but structure stays same
Testing A/B variations of layouts
Migrating layouts between sites

Automation = sanity!!

Architecture: JSON Config → Script → Page Builder

Three components:

JSON configuration (layout structure + content variables)
PHP script (reads JSON, generates page builder meta)
WP-CLI command (creates pages programmatically)

Workflow:

cities.json → automation-script.php → wp-cli → 50 pages created

Supported Page Builders

This technique works with:

Elementor (stores layouts in postmeta _elementor_data)
Divi (stores layouts in _et_pb_page_layout)
Beaver Builder (stores layouts in _fl_builder_data)
WPBakery (stores layouts as shortcodes in post_content)
Oxygen (stores layouts in postmeta ct_builder_shortcodes)

Key insight: All page builders store layouts as JSON or shortcodes in database!!

Example 1: Elementor Automation

Step 1: Export Template as JSON

Create one perfect page manually in Elementor

Export template:

Elementor → Tools → Export Template

Saved as: template.json

Structure:

{
  "content": [
    {
      "id": "abc123",
      "elType": "section",
      "elements": [
        {
          "elType": "column",
          "elements": [
            {
              "elType": "widget",
              "widgetType": "heading",
              "settings": {
                "title": "{{CITY_NAME}} Services"
              }
            }
          ]
        }
      ]
    }
  ]
}

Step 2: Create City Data JSON

File: cities.json

[
  {
    "city": "Chicago",
    "state": "IL",
    "zip": "60601",
    "phone": "(312) 555-0100"
  },
  {
    "city": "Boston",
    "state": "MA",
    "zip": "02108",
    "phone": "(617) 555-0200"
  },
  {
    "city": "Seattle",
    "state": "WA",
    "zip": "98101",
    "phone": "(206) 555-0300"
  }
]

Step 3: PHP Automation Script

File: generate-elementor-pages.php

<?php
/**
 * Elementor Page Generator
 * Usage: php generate-elementor-pages.php
 */

// Load WordPress
require_once('/path/to/wp-load.php');

// Load data
$template = json_decode(file_get_contents('template.json'), true);
$cities = json_decode(file_get_contents('cities.json'), true);

foreach ($cities as $city) {
    // Replace placeholders in template
    $layout = replace_placeholders($template, [
        '{{CITY_NAME}}' => $city['city'],
        '{{STATE}}' => $city['state'],
        '{{ZIP}}' => $city['zip'],
        '{{PHONE}}' => $city['phone']
    ]);

    // Create page
    $page_id = wp_insert_post([
        'post_title'   => $city['city'] . ' Services',
        'post_status'  => 'publish',
        'post_type'    => 'page',
        'post_content' => '' // Elementor uses meta, not content
    ]);

    if (!is_wp_error($page_id)) {
        // Save Elementor data
        update_post_meta($page_id, '_elementor_data', wp_slash(json_encode($layout['content'])));
        update_post_meta($page_id, '_elementor_edit_mode', 'builder');
        update_post_meta($page_id, '_elementor_template_type', 'wp-page');
        update_post_meta($page_id, '_elementor_version', '3.16.0');

        echo "✅ Created: {$city['city']} (ID: {$page_id})\n";
    }
}

function replace_placeholders($data, $replacements) {
    $json = json_encode($data);

    foreach ($replacements as $placeholder => $value) {
        $json = str_replace($placeholder, $value, $json);
    }

    return json_decode($json, true);
}

echo "\n✨ Generation complete!\n";

Step 4: Run Script

php generate-elementor-pages.php

Output:

✅ Created: Chicago (ID: 123)
✅ Created: Boston (ID: 124)
✅ Created: Seattle (ID: 125)

✨ Generation complete!

3 pages created in seconds!!

Example 2: Divi Layout Automation

Divi Storage Format

Divi stores layouts as JSON in _et_pb_page_layout postmeta

Sample Divi JSON:

[
  {
    "type": "et_pb_section",
    "attrs": {
      "background_color": "#ffffff"
    },
    "content": [
      {
        "type": "et_pb_row",
        "content": [
          {
            "type": "et_pb_column",
            "content": [
              {
                "type": "et_pb_text",
                "attrs": {
                  "content": "<h1>{{CITY_NAME}} Professional Services</h1>"
                }
              }
            ]
          }
        ]
      }
    ]
  }
]

Divi Automation Script

<?php
require_once('/path/to/wp-load.php');

$template = json_decode(file_get_contents('divi-template.json'), true);
$cities = json_decode(file_get_contents('cities.json'), true);

foreach ($cities as $city) {
    $layout = replace_placeholders($template, [
        '{{CITY_NAME}}' => $city['city'],
        '{{STATE}}' => $city['state']
    ]);

    $page_id = wp_insert_post([
        'post_title'   => $city['city'] . ' Services',
        'post_status'  => 'publish',
        'post_type'    => 'page'
    ]);

    if (!is_wp_error($page_id)) {
        // Divi-specific meta
        update_post_meta($page_id, '_et_pb_use_builder', 'on');
        update_post_meta($page_id, '_et_pb_page_layout', wp_slash(json_encode($layout)));
        update_post_meta($page_id, '_et_pb_old_content', '');

        echo "✅ Divi page: {$city['city']}\n";
    }
}

Example 3: WP-CLI Integration

Create WP-CLI Command

File: wp-content/mu-plugins/page-generator.php

<?php
/**
 * Plugin Name: Page Generator CLI
 */

if (defined('WP_CLI') && WP_CLI) {
    WP_CLI::add_command('generate pages', 'Page_Generator_CLI');
}

class Page_Generator_CLI {

    /**
     * Generate pages from template
     * 
     * ## OPTIONS
     * 
     * --template=<file>
     * : Template JSON file
     * 
     * --data=<file>
     * : Data JSON file
     * 
     * --builder=<name>
     * : Page builder (elementor|divi|beaver)
     * 
     * ## EXAMPLES
     * 
     *     wp generate pages --template=template.json --data=cities.json --builder=elementor
     */
    public function __invoke($args, $assoc_args) {
        $template_file = $assoc_args['template'];
        $data_file = $assoc_args['data'];
        $builder = $assoc_args['builder'];

        if (!file_exists($template_file)) {
            WP_CLI::error("Template file not found: {$template_file}");
        }

        if (!file_exists($data_file)) {
            WP_CLI::error("Data file not found: {$data_file}");
        }

        $template = json_decode(file_get_contents($template_file), true);
        $data = json_decode(file_get_contents($data_file), true);

        $generated = 0;

        foreach ($data as $item) {
            $page_id = $this->create_page($template, $item, $builder);

            if ($page_id) {
                WP_CLI::success("Created page ID {$page_id}: {$item['city']}");
                $generated++;
            }
        }

        WP_CLI::success("Generated {$generated} pages!");
    }

    private function create_page($template, $data, $builder) {
        // Replace placeholders
        $layout = $this->replace_placeholders($template, $data);

        // Create page
        $page_id = wp_insert_post([
            'post_title'   => $data['city'] . ' Services',
            'post_status'  => 'publish',
            'post_type'    => 'page'
        ]);

        if (is_wp_error($page_id)) {
            return false;
        }

        // Save builder-specific meta
        switch ($builder) {
            case 'elementor':
                update_post_meta($page_id, '_elementor_data', wp_slash(json_encode($layout)));
                update_post_meta($page_id, '_elementor_edit_mode', 'builder');
                break;

            case 'divi':
                update_post_meta($page_id, '_et_pb_use_builder', 'on');
                update_post_meta($page_id, '_et_pb_page_layout', wp_slash(json_encode($layout)));
                break;

            case 'beaver':
                update_post_meta($page_id, '_fl_builder_enabled', '1');
                update_post_meta($page_id, '_fl_builder_data', $layout);
                break;
        }

        return $page_id;
    }

    private function replace_placeholders($data, $replacements) {
        $json = json_encode($data);

        // Build replacement map
        $search = [];
        $replace = [];

        foreach ($replacements as $key => $value) {
            $search[] = '{{' . strtoupper($key) . '}}';
            $replace[] = $value;
        }

        $json = str_replace($search, $replace, $json);

        return json_decode($json, true);
    }
}

Usage

# Generate 50 city pages
wp generate pages \
  --template=elementor-template.json \
  --data=cities.json \
  --builder=elementor

# Output:
# Success: Created page ID 123: Chicago
# Success: Created page ID 124: Boston
# Success: Created page ID 125: Seattle
# Success: Generated 50 pages!

Advanced: REST API Integration

Create REST Endpoint

<?php
add_action('rest_api_init', function() {
    register_rest_route('page-gen/v1', '/create', [
        'methods'  => 'POST',
        'callback' => 'generate_page_via_api',
        'permission_callback' => function() {
            return current_user_can('edit_pages');
        }
    ]);
});

function generate_page_via_api($request) {
    $params = $request->get_json_params();

    $template = $params['template'];
    $data = $params['data'];
    $builder = $params['builder'];

    // Replace placeholders
    $layout = replace_placeholders($template, $data);

    // Create page
    $page_id = wp_insert_post([
        'post_title'   => $data['title'],
        'post_status'  => 'publish',
        'post_type'    => 'page'
    ]);

    // Save builder meta
    if ($builder === 'elementor') {
        update_post_meta($page_id, '_elementor_data', wp_slash(json_encode($layout)));
        update_post_meta($page_id, '_elementor_edit_mode', 'builder');
    }

    return new WP_REST_Response([
        'success' => true,
        'page_id' => $page_id,
        'url'     => get_permalink($page_id)
    ], 201);
}

Call API from External Script

// Node.js example
const axios = require('axios');

async function generatePages() {
    const template = require('./template.json');
    const cities = require('./cities.json');

    for (const city of cities) {
        const response = await axios.post(
            'https://yoursite.com/wp-json/page-gen/v1/create',
            {
                template: template,
                data: {
                    title: `${city.city} Services`,
                    ...city
                },
                builder: 'elementor'
            },
            {
                auth: {
                    username: 'admin',
                    password: 'application-password'
                }
            }
        );

        console.log(`✅ Created: ${response.data.url}`);
    }
}

generatePages();

Real-World Use Case: Agency Workflow

Client: National HVAC Company

Need: Landing page for every city (300+ locations)

Layout:

Hero with city name
Service list
Local testimonials
Contact form with city phone
Map embed with city coordinates

Manual time: 300 × 20 minutes = 100 hours!!

Automated time:

Template creation: 2 hours
CSV data prep: 1 hour
Script development: 3 hours
Generation: 5 minutes
Total: 6 hours = 94 hours saved!!

Implementation

Data file: hvac-locations.csv

city,state,zip,phone,lat,lng
Chicago,IL,60601,(312) 555-0100,41.8781,-87.6298
Boston,MA,02108,(617) 555-0200,42.3601,-71.0589

Script:

<?php
require_once('wp-load.php');

$template = json_decode(file_get_contents('hvac-template.json'), true);
$csv = array_map('str_getcsv', file('hvac-locations.csv'));
$headers = array_shift($csv);

foreach ($csv as $row) {
    $location = array_combine($headers, $row);

    $layout = replace_placeholders($template, [
        '{{CITY}}' => $location['city'],
        '{{STATE}}' => $location['state'],
        '{{PHONE}}' => $location['phone'],
        '{{LAT}}' => $location['lat'],
        '{{LNG}}' => $location['lng']
    ]);

    $page_id = wp_insert_post([
        'post_title' => "HVAC Services in {$location['city']}, {$location['state']}",
        'post_name'  => sanitize_title("hvac-{$location['city']}-{$location['state']}"),
        'post_status' => 'publish',
        'post_type' => 'page'
    ]);

    update_post_meta($page_id, '_elementor_data', wp_slash(json_encode($layout)));
    update_post_meta($page_id, '_elementor_edit_mode', 'builder');

    // SEO meta
    update_post_meta($page_id, '_yoast_wpseo_title', 
        "HVAC Services {$location['city']}, {$location['state']} | Company Name");
    update_post_meta($page_id, '_yoast_wpseo_metadesc',
        "Professional HVAC services in {$location['city']}, {$location['state']}. Call {$location['phone']} today!");

    echo "✅ {$location['city']}, {$location['state']}\n";
}

Result: 300 pages generated in 5 minutes!!

Handling Dynamic Content

ACF Integration

// Add ACF fields to generated page
update_field('service_area', $location['city'], $page_id);
update_field('phone_number', $location['phone'], $page_id);
update_field('map_coordinates', [
    'lat' => $location['lat'],
    'lng' => $location['lng']
], $page_id);

Dynamic Elementor Widgets

{
  "elType": "widget",
  "widgetType": "text-editor",
  "settings": {
    "editor": "[acf field='service_area']"
  }
}

Elementor renders ACF shortcode dynamically!!

Error Handling & Logging

<?php
class Page_Generator {
    private $log = [];

    public function generate($template, $data) {
        foreach ($data as $item) {
            try {
                $page_id = $this->create_page($template, $item);
                $this->log[] = "✅ Success: {$item['city']} (ID: {$page_id})";
            } catch (Exception $e) {
                $this->log[] = "❌ Error: {$item['city']} - {$e->getMessage()}";
            }
        }

        // Save log
        file_put_contents('generation-log.txt', implode("\n", $this->log));
    }

    private function create_page($template, $item) {
        $page_id = wp_insert_post([
            'post_title' => $item['city'] . ' Services',
            'post_status' => 'publish',
            'post_type' => 'page'
        ]);

        if (is_wp_error($page_id)) {
            throw new Exception($page_id->get_error_message());
        }

        // Validate layout before saving
        if (!$this->validate_layout($template)) {
            throw new Exception('Invalid layout structure');
        }

        $layout = $this->replace_placeholders($template, $item);
        update_post_meta($page_id, '_elementor_data', wp_slash(json_encode($layout)));

        return $page_id;
    }

    private function validate_layout($layout) {
        // Check required fields exist
        return isset($layout['content']) && is_array($layout['content']);
    }
}

Bottom Line

Stop clicking page builders for repetitive layouts!!

Automation wins:

100+ pages: Minutes not days
Zero human error
Consistent layouts guaranteed
Easy bulk updates (regenerate all pages)
Client thinks you're wizard!!

My typical workflow:

Build one perfect template manually (1 hour)
Export as JSON (30 seconds)
Prepare data CSV/JSON (30 minutes)
Write generation script (2 hours)
Run script (2 minutes)

ROI: Pays for itself after 10 pages!!

For 50+ pages: Automation is NON-NEGOTIABLE!!

Page builder automation = agency superpower!! 🚀

This article contains affiliate links!

Using Browser Profiler Tools to Fix Layout Shifts in WordPress Themes

Martijn Assie — Sun, 01 Feb 2026 22:37:24 +0000

Client complains: "Content jumps around when page loads - looks super janky!!"

Their CLS score: 0.42 (HORRIBLE - Google penalizes above 0.1)

Me opening DevTools: Found 8 layout shifts in 3 seconds!! Header image loading without dimensions, web fonts causing text reflow, lazy-loaded ads pushing content down.

After fixes using Performance Profiler: CLS 0.03!!

Identified exact elements shifting
Traced timing of each shift
Fixed with reserve space CSS
Zero guesswork, pure data!!

Here's how to use browser profiler tools to hunt down and eliminate layout shifts:

What is Cumulative Layout Shift (CLS)?

Layout shift = visible content moving unexpectedly

Examples:

Reading article → image loads → text jumps down (you lose your place!)
About to click button → ad loads → click wrong thing!!
Header loads → pushes content → annoying!!

CLS score:

Good: <0.1
Needs improvement: 0.1-0.25
Poor: >0.25

Google uses CLS as ranking factor!! High CLS = lower search rankings.

Opening Chrome DevTools Performance Panel

Step 1: Open DevTools

Three ways:

Right-click page → Inspect
Or press F12
Or Cmd+Option+I (Mac) / Ctrl+Shift+I (Windows)

Step 2: Navigate to Performance Tab

Click "Performance" tab in DevTools

Or faster:

Cmd+Shift+P (Mac) / Ctrl+Shift+P (Windows)
Type "Performance"
Select "Show Performance"

Step 3: Configure Capture Settings

Click gear icon ⚙️ in top-right

Enable:

✅ Screenshots (see visual timeline)
✅ Web Vitals (track CLS/LCP/FID)
✅ Enable advanced paint instrumentation

CPU throttling:

No throttling (fast testing)
4x slowdown (simulates mobile)
6x slowdown (simulates low-end devices)

Network throttling:

No throttling
Fast 3G
Slow 3G (exposes timing issues!)

Pro tip: Use "Slow 3G + 6x CPU" to make layout shifts OBVIOUS!!

Recording a Performance Profile

Method 1: Reload and Profile

Click ⟳ icon (Start profiling and reload page)

DevTools:

Starts recording
Reloads page
Stops automatically when page settles

Use this for initial page load testing

Method 2: Manual Recording

Click ● Record button

Interact with page:

Scroll down
Click buttons
Open menus
Lazy load content

Click ■ Stop when done

Use this for interaction testing

Analyzing Layout Shifts in Performance Timeline

The Experience Lane

Look for purple bars labeled "LS" (Layout Shift)

Timeline view:
------------------------------------
| Screenshots                      |
| Experience: [LS][LS]    [LS]    |
| Frames                           |
| Interactions                     |
| Network                          |
------------------------------------

Each purple diamond = one layout shift

Size of diamond = severity of shift

Inspecting Individual Shifts

Click purple diamond:

Bottom panel shows details:

Layout Shift
Score: 0.175
Cumulative Score: 0.23
Had Recent Input: false

Moved from: [coordinates]
Moved to: [coordinates]

Affected Nodes: 3

Hover over "Moved from/to":

DevTools highlights affected elements on page screenshot!!

Reading the Summary

Key fields:

Score: Individual shift impact (0-1 scale)

Cumulative Score: Running total CLS

Had Recent Input:

false = counts toward CLS
true = within 500ms of user action (ignored!)

Affected Nodes: Number of elements that moved

startTime: When shift occurred (milliseconds)

Common WordPress Layout Shift Culprits

1. Images Without Dimensions

Problem:

<img src="header.jpg">

Browser doesn't know size → reserves 0 space → image loads → content shifts down!!

DevTools shows:

Layout Shift
Score: 0.28
Element: img.wp-post-image

Fix:

<img src="header.jpg" width="1200" height="600">

Or CSS:

img {
    aspect-ratio: 16 / 9;
    width: 100%;
    height: auto;
}

Verify in DevTools:

Record again
Layout shift GONE ✅

2. Web Fonts Loading (FOIT/FOUT)

Problem: Text invisible → font loads → text appears → layout shifts

DevTools shows:

Layout Shift  
Score: 0.12
Element: h1.entry-title
Timing: 847ms (after font load)

Fix with font-display:

@font-face {
    font-family: 'CustomFont';
    src: url('/fonts/custom.woff2');
    font-display: swap; /* Show fallback immediately */
}

Better: Preload fonts

<link rel="preload" 
      href="/fonts/custom.woff2" 
      as="font" 
      type="font/woff2" 
      crossorigin>

Verify:

Record profile
Check Experience lane
Font-related shift eliminated ✅

3. Ads and Embeds

Problem: Content loads → ad/embed loads → content pushed down

DevTools shows:

Layout Shift
Score: 0.35 (HUGE!)
Element: div.ad-container
Timing: 1,240ms

Fix: Reserve space

.ad-container {
    min-height: 250px; /* Ad size */
    display: flex;
    align-items: center;
    justify-content: center;
    background: #f0f0f0;
}

.ad-container::before {
    content: 'Advertisement';
    color: #999;
}

For dynamic ad sizes:

.ad-container {
    aspect-ratio: 16 / 9;
    min-height: 250px;
}

4. Lazy-Loaded Content

Problem: Scroll → content loads → page jumps

DevTools Interaction Recording:

Click Record ●
Scroll down slowly
Click Stop ■

See shifts in timeline as you scroll

Fix: Intersection Observer with placeholder

const observer = new IntersectionObserver((entries) => {
    entries.forEach(entry => {
        if (entry.isIntersecting) {
            const img = entry.target;
            // Set dimensions BEFORE loading
            img.width = img.dataset.width;
            img.height = img.dataset.height;
            img.src = img.dataset.src;
            observer.unobserve(img);
        }
    });
});

document.querySelectorAll('img[data-src]').forEach(img => {
    observer.observe(img);
});

5. Dynamic Content Injection

WordPress culprit: Plugins injecting content after page load

DevTools shows:

Layout Shift
Score: 0.19
Element: div.injected-content
Timing: 980ms
Source: notification-bar.js

Fix: Reserve space or animate in

.notification-bar {
    height: 0;
    overflow: hidden;
    transition: height 0.3s ease;
}

.notification-bar.loaded {
    height: 60px; /* Known height */
}

JavaScript:

// Bad: Just inserting
document.body.insertAdjacentHTML('afterbegin', notificationHTML);

// Good: Set height first
const bar = document.createElement('div');
bar.style.height = '60px';
bar.innerHTML = notificationHTML;
document.body.insertBefore(bar, document.body.firstChild);

Advanced: Layout Shift Regions Visualization

Enable Real-Time Highlighting

DevTools → More tools (⋮) → Rendering

Enable:

✅ Layout Shift Regions

Now interact with page:

Blue rectangles flash on elements that shift!!

Use this to:

Spot shifts visually
Test live as you develop
Verify fixes immediately

Performance Insights Panel (New!)

Access Insights

After recording, click Insights tab (sidebar icon)

Shows:

Layout Shift Culprits
━━━━━━━━━━━━━━━━━━━━━━━
Worst cluster: 0.31
  ↳ img.header-image (0.18)
  ↳ div.ad-slot (0.13)

Total shifts: 5
Cumulative score: 0.42

Click culprit → jumps to element in timeline

Shift Clusters

What is cluster?

Multiple shifts within 1 second + within 5 seconds of previous shift = cluster

Why clusters matter:

Google scores clusters, not individual shifts!!

DevTools shows:

Cluster 1: Score 0.25
  - Shift 1: 0.12 (847ms)
  - Shift 2: 0.08 (912ms)
  - Shift 3: 0.05 (1,103ms)

Fix entire cluster together for max impact

Measuring CLS with JavaScript

Real User Monitoring Script

/**
 * Track CLS in real WordPress sessions
 */
let cls = 0;
const clsEntries = [];

const observer = new PerformanceObserver((list) => {
    for (const entry of list.getEntries()) {
        // Ignore shifts from user input
        if (!entry.hadRecentInput) {
            cls += entry.value;
            clsEntries.push({
                value: entry.value,
                time: entry.startTime,
                sources: entry.sources.map(source => ({
                    node: source.node,
                    previousRect: source.previousRect,
                    currentRect: source.currentRect
                }))
            });

            console.log('Layout Shift:', {
                score: entry.value,
                cumulative: cls,
                element: entry.sources[0]?.node
            });
        }
    }
});

observer.observe({ type: 'layout-shift', buffered: true });

// Report CLS on page unload
window.addEventListener('beforeunload', () => {
    console.log('Final CLS:', cls);
    console.log('Total shifts:', clsEntries.length);

    // Send to analytics
    if (typeof gtag !== 'undefined') {
        gtag('event', 'cls_score', {
            value: Math.round(cls * 1000), // Convert to integer
            metric_id: 'cls'
        });
    }
});

Add to WordPress:

<?php
function enqueue_cls_monitor() {
    if (current_user_can('administrator') && WP_DEBUG) {
        wp_enqueue_script(
            'cls-monitor',
            get_stylesheet_directory_uri() . '/js/cls-monitor.js',
            array(),
            '1.0.0',
            true
        );
    }
}
add_action('wp_enqueue_scripts', 'enqueue_cls_monitor');

Debugging Specific WordPress Themes

Twenty Twenty-Four

Common issues:

Query block lazy loading
Featured image dimensions missing
Navigation menu height changes

DevTools findings:

Shift at 340ms: nav.wp-block-navigation (0.08)
Shift at 680ms: img.wp-block-cover (0.15)

Fixes:

/* Reserve nav height */
.wp-block-navigation {
    min-height: 60px;
}

/* Set cover image aspect ratio */
.wp-block-cover {
    aspect-ratio: 16 / 9;
}

Astra Theme

Common issues:

Custom header height dynamic
Mobile menu toggle
Sticky header activation

DevTools process:

Record with mobile viewport
Toggle menu
Check Experience lane

Fix:

/* Prevent header height change */
.ast-main-header-wrap {
    height: 80px;
}

/* Reserve space for mobile menu */
.ast-mobile-menu-buttons {
    width: 50px;
}

GeneratePress

Common issues:

Slideout navigation
Dynamic spacing
Widget areas

Fix in Customize:

Layout → Container → Set fixed width (1200px)
Colors → Background → Set before content loads

Testing Workflow

1. Baseline Test

1. Open DevTools Performance
2. Enable Slow 3G + 6x CPU throttling
3. Record reload
4. Note CLS score and culprits

2. Identify Issues

1. Check Experience lane for purple diamonds
2. Click each shift
3. Note affected elements
4. Screenshot or export trace

3. Implement Fixes

1. Add image dimensions
2. Preload fonts
3. Reserve space for dynamic content
4. Set aspect ratios

4. Verify Fixes

1. Hard refresh (Cmd+Shift+R / Ctrl+Shift+F5)
2. Record new profile
3. Compare CLS scores
4. Confirm shifts eliminated

5. Real-World Testing

1. Test on actual mobile device
2. Test with real network (not throttled)
3. Use PageSpeed Insights for field data
4. Monitor real user CLS with analytics

Exporting and Sharing Traces

Save profile for later:

Performance panel → Click Download (⬇️)

Saves as .json file

Load trace:

Performance panel → Click Upload (⬆️)

Share with team:

Send .json file
Teammates load in their DevTools
Everyone sees exact same data!!

Bottom Line

Stop guessing at layout shift causes!!

Browser profiler tools show:

Exact elements shifting
Precise timing
Severity scores
Visual timeline
Everything you need to fix CLS!!

My workflow:

Record performance profile (30 seconds)
Identify shifts in Experience lane (2 minutes)
Implement fixes (10 minutes)
Verify improvements (30 seconds)

Total time: 15 minutes to fix critical UX issue!!

vs old way:

Guess at problems
Try random fixes
Hope it works
Users still complain
Complete waste of time!!

DevTools Performance panel = surgical precision for layout shift debugging!! 🎯

This article contains affiliate links!

Version-Controlling WordPress Customizer Settings With Git

Martijn Assie — Sun, 01 Feb 2026 21:55:19 +0000

Developer switches to new laptop: "Wait, where are all the customizer settings from yesterday??"

The settings: Trapped in database, zero version control, changes completely lost!!

My workflow now: Customizer settings auto-export to JSON files, committed to Git!!

Every save = JSON file updated
Full Git history of color changes, typography tweaks, layout adjustments
Deploy settings with code: git pull && wp customizer import
Never lose settings again!!

Here's the complete technical implementation:

The Problem With Customizer Settings

Current WordPress workflow:

Developer changes header color → Saved to wp_options table

Problems:

No version history
Can't see what changed
Can't revert easily
Can't deploy with code
Lost if database corrupts
Completely disconnected from Git workflow!!

What we need:

Developer changes header color → JSON file updated → Git commit → Deploy everywhere

Architecture: Database to Filesystem Sync

Core Concept

<?php
/**
 * Customizer Settings Version Control
 * 
 * Syncs theme_mods to JSON files for Git tracking
 */

class Customizer_Git_Sync {

    private $settings_dir;
    private $theme_slug;

    public function __construct() {
        $this->theme_slug = get_stylesheet();

        // Store in theme directory for Git tracking
        $this->settings_dir = get_stylesheet_directory() . '/customizer-settings';

        // Create directory if doesn't exist
        if (!file_exists($this->settings_dir)) {
            wp_mkdir_p($this->settings_dir);
        }

        $this->init_hooks();
    }

    private function init_hooks() {
        // Export on customizer save
        add_action('customize_save_after', array($this, 'export_on_save'));

        // Import on theme activation
        add_action('after_switch_theme', array($this, 'import_on_activation'));

        // Add export/import buttons to customizer
        add_action('customize_controls_enqueue_scripts', array($this, 'enqueue_customizer_scripts'));
        add_action('customize_register', array($this, 'add_export_import_section'));

        // AJAX handlers
        add_action('wp_ajax_export_customizer_settings', array($this, 'ajax_export'));
        add_action('wp_ajax_import_customizer_settings', array($this, 'ajax_import'));
    }

    /**
     * Export settings to JSON
     */
    public function export_settings() {
        // Get all theme mods
        $mods = get_theme_mods();

        if (empty($mods)) {
            return false;
        }

        // Get current WordPress customizer settings
        $settings = array();

        // Theme mods
        $settings['theme_mods'] = $mods;

        // Custom CSS (if exists)
        $custom_css = wp_get_custom_css();
        if ($custom_css) {
            $settings['custom_css'] = $custom_css;
        }

        // Site title/tagline (stored in options, not theme_mods)
        $settings['options'] = array(
            'blogname' => get_option('blogname'),
            'blogdescription' => get_option('blogdescription'),
        );

        // Add metadata
        $settings['_meta'] = array(
            'theme' => $this->theme_slug,
            'exported_at' => current_time('mysql'),
            'wp_version' => get_bloginfo('version'),
            'exported_by' => wp_get_current_user()->user_login,
        );

        // Convert to JSON
        $json = json_encode($settings, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);

        // Save to file
        $filename = $this->settings_dir . '/customizer-settings.json';
        $result = file_put_contents($filename, $json);

        if ($result) {
            // Create Git-friendly changelog
            $this->create_changelog($settings);
        }

        return $result !== false;
    }

    /**
     * Create human-readable changelog
     */
    private function create_changelog($settings) {
        $changelog_file = $this->settings_dir . '/CHANGELOG.md';

        $changelog = "# Customizer Settings Changelog\n\n";
        $changelog .= "## " . date('Y-m-d H:i:s') . "\n\n";
        $changelog .= "Changed by: " . wp_get_current_user()->user_login . "\n\n";

        // List major settings
        if (isset($settings['theme_mods'])) {
            $changelog .= "### Theme Modifications\n\n";
            foreach ($settings['theme_mods'] as $key => $value) {
                if (is_array($value) || is_object($value)) {
                    $changelog .= "- **{$key}**: " . json_encode($value) . "\n";
                } else {
                    $changelog .= "- **{$key}**: {$value}\n";
                }
            }
        }

        // Append to changelog (keep history)
        file_put_contents($changelog_file, $changelog . "\n---\n\n", FILE_APPEND);
    }

    /**
     * Import settings from JSON
     */
    public function import_settings() {
        $filename = $this->settings_dir . '/customizer-settings.json';

        if (!file_exists($filename)) {
            return new WP_Error('file_not_found', 'Settings file not found');
        }

        $json = file_get_contents($filename);
        $settings = json_decode($json, true);

        if (json_last_error() !== JSON_ERROR_NONE) {
            return new WP_Error('json_error', 'Invalid JSON: ' . json_last_error_msg());
        }

        // Verify theme matches
        if (isset($settings['_meta']['theme']) && $settings['_meta']['theme'] !== $this->theme_slug) {
            return new WP_Error('theme_mismatch', 'Settings are for a different theme');
        }

        // Import theme mods
        if (isset($settings['theme_mods'])) {
            foreach ($settings['theme_mods'] as $key => $value) {
                set_theme_mod($key, $value);
            }
        }

        // Import custom CSS
        if (isset($settings['custom_css'])) {
            wp_update_custom_css_post($settings['custom_css']);
        }

        // Import options
        if (isset($settings['options'])) {
            foreach ($settings['options'] as $option => $value) {
                update_option($option, $value);
            }
        }

        return true;
    }

    /**
     * Auto-export after customizer save
     */
    public function export_on_save($wp_customize) {
        $this->export_settings();

        // Log for debugging
        if (defined('WP_DEBUG') && WP_DEBUG) {
            error_log('Customizer settings exported to JSON');
        }
    }

    /**
     * Auto-import on theme activation
     */
    public function import_on_activation() {
        $result = $this->import_settings();

        if (is_wp_error($result)) {
            error_log('Customizer import error: ' . $result->get_error_message());
        }
    }

    /**
     * Add export/import section to customizer
     */
    public function add_export_import_section($wp_customize) {
        $wp_customize->add_section('export_import_section', array(
            'title' => __('Git Sync', 'textdomain'),
            'description' => __('Version control for customizer settings', 'textdomain'),
            'priority' => 200,
        ));

        // Export button
        $wp_customize->add_setting('export_settings', array(
            'sanitize_callback' => '__return_false',
        ));

        $wp_customize->add_control('export_settings', array(
            'type' => 'button',
            'section' => 'export_import_section',
            'label' => __('Export to JSON', 'textdomain'),
            'description' => __('Download settings as JSON file', 'textdomain'),
            'input_attrs' => array(
                'class' => 'button button-primary',
                'value' => __('Export', 'textdomain'),
            ),
        ));

        // Import button
        $wp_customize->add_setting('import_settings', array(
            'sanitize_callback' => '__return_false',
        ));

        $wp_customize->add_control('import_settings', array(
            'type' => 'button',
            'section' => 'export_import_section',
            'label' => __('Import from JSON', 'textdomain'),
            'description' => __('Load settings from JSON file', 'textdomain'),
            'input_attrs' => array(
                'class' => 'button',
                'value' => __('Import', 'textdomain'),
            ),
        ));

        // Git status display
        $wp_customize->add_setting('git_status', array(
            'sanitize_callback' => '__return_false',
        ));

        $wp_customize->add_control('git_status', array(
            'type' => 'hidden',
            'section' => 'export_import_section',
            'description' => $this->get_git_status_html(),
        ));
    }

    /**
     * Get Git status for display
     */
    private function get_git_status_html() {
        $git_dir = get_stylesheet_directory();

        // Check if Git repo exists
        if (!is_dir($git_dir . '/.git')) {
            return '<p style="color: #dc3232;">⚠️ Not a Git repository</p>';
        }

        // Get Git status
        $output = shell_exec("cd {$git_dir} && git status --porcelain customizer-settings/");

        if (empty($output)) {
            return '<p style="color: #46b450;">✓ Settings committed</p>';
        }

        return '<p style="color: #ffba00;">⚠️ Uncommitted changes detected</p>' .
               '<pre style="background: #f0f0f1; padding: 10px; font-size: 11px;">' . 
               esc_html($output) . 
               '</pre>';
    }

    /**
     * Enqueue customizer scripts
     */
    public function enqueue_customizer_scripts() {
        wp_enqueue_script(
            'customizer-git-sync',
            get_stylesheet_directory_uri() . '/js/customizer-git-sync.js',
            array('jquery', 'customize-controls'),
            '1.0.0',
            true
        );

        wp_localize_script('customizer-git-sync', 'customizerGitSync', array(
            'ajax_url' => admin_url('admin-ajax.php'),
            'nonce' => wp_create_nonce('customizer_git_sync'),
        ));
    }

    /**
     * AJAX export handler
     */
    public function ajax_export() {
        check_ajax_referer('customizer_git_sync', 'nonce');

        if (!current_user_can('edit_theme_options')) {
            wp_send_json_error('Insufficient permissions');
        }

        $result = $this->export_settings();

        if ($result) {
            wp_send_json_success('Settings exported successfully');
        } else {
            wp_send_json_error('Export failed');
        }
    }

    /**
     * AJAX import handler
     */
    public function ajax_import() {
        check_ajax_referer('customizer_git_sync', 'nonce');

        if (!current_user_can('edit_theme_options')) {
            wp_send_json_error('Insufficient permissions');
        }

        $result = $this->import_settings();

        if (is_wp_error($result)) {
            wp_send_json_error($result->get_error_message());
        } else {
            wp_send_json_success('Settings imported successfully');
        }
    }
}

// Initialize
function init_customizer_git_sync() {
    if (current_user_can('edit_theme_options')) {
        new Customizer_Git_Sync();
    }
}
add_action('init', 'init_customizer_git_sync');

JavaScript for Customizer Interface

Create /js/customizer-git-sync.js:

(function($) {
    'use strict';

    wp.customize.bind('ready', function() {

        // Export button handler
        $('input[value="Export"]').on('click', function(e) {
            e.preventDefault();

            $.ajax({
                url: customizerGitSync.ajax_url,
                type: 'POST',
                data: {
                    action: 'export_customizer_settings',
                    nonce: customizerGitSync.nonce
                },
                success: function(response) {
                    if (response.success) {
                        alert('✓ Settings exported to JSON!\\n\\nCommit the changes to Git.');
                    } else {
                        alert('✗ Export failed: ' + response.data);
                    }
                },
                error: function() {
                    alert('✗ AJAX error occurred');
                }
            });
        });

        // Import button handler
        $('input[value="Import"]').on('click', function(e) {
            e.preventDefault();

            if (!confirm('Import settings from JSON file?\\n\\nThis will overwrite current settings!')) {
                return;
            }

            $.ajax({
                url: customizerGitSync.ajax_url,
                type: 'POST',
                data: {
                    action: 'import_customizer_settings',
                    nonce: customizerGitSync.nonce
                },
                success: function(response) {
                    if (response.success) {
                        alert('✓ Settings imported!\\n\\nRefreshing customizer...');
                        location.reload();
                    } else {
                        alert('✗ Import failed: ' + response.data);
                    }
                },
                error: function() {
                    alert('✗ AJAX error occurred');
                }
            });
        });

        // Auto-save indicator
        wp.customize.state('saved').bind(function(saved) {
            if (saved) {
                console.log('Customizer saved - exporting to JSON...');
            }
        });
    });

})(jQuery);

WP-CLI Commands

Create /wp-content/mu-plugins/customizer-cli.php:

<?php
/**
 * WP-CLI commands for customizer settings
 */

if (defined('WP_CLI') && WP_CLI) {

    class Customizer_CLI_Commands {

        /**
         * Export customizer settings to JSON
         *
         * ## EXAMPLES
         *
         *     wp customizer export
         */
        public function export($args, $assoc_args) {
            $sync = new Customizer_Git_Sync();
            $result = $sync->export_settings();

            if ($result) {
                WP_CLI::success('Settings exported to JSON');
                WP_CLI::log('File: ' . get_stylesheet_directory() . '/customizer-settings/customizer-settings.json');
            } else {
                WP_CLI::error('Export failed');
            }
        }

        /**
         * Import customizer settings from JSON
         *
         * ## EXAMPLES
         *
         *     wp customizer import
         */
        public function import($args, $assoc_args) {
            $sync = new Customizer_Git_Sync();
            $result = $sync->import_settings();

            if (is_wp_error($result)) {
                WP_CLI::error($result->get_error_message());
            } else {
                WP_CLI::success('Settings imported from JSON');
            }
        }

        /**
         * Show diff between database and JSON file
         *
         * ## EXAMPLES
         *
         *     wp customizer diff
         */
        public function diff($args, $assoc_args) {
            $theme_dir = get_stylesheet_directory();
            $json_file = $theme_dir . '/customizer-settings/customizer-settings.json';

            if (!file_exists($json_file)) {
                WP_CLI::error('JSON file not found');
                return;
            }

            // Get current settings
            $current = array(
                'theme_mods' => get_theme_mods(),
                'custom_css' => wp_get_custom_css(),
            );

            // Get JSON settings
            $json = json_decode(file_get_contents($json_file), true);

            // Compare
            $diff = array_diff_assoc($current['theme_mods'], $json['theme_mods']);

            if (empty($diff)) {
                WP_CLI::success('No differences found');
            } else {
                WP_CLI::log('Differences detected:');
                foreach ($diff as $key => $value) {
                    WP_CLI::log("  $key:");
                    WP_CLI::log("    Database: " . json_encode($value));
                    WP_CLI::log("    JSON:     " . json_encode($json['theme_mods'][$key] ?? 'not set'));
                }
            }
        }
    }

    WP_CLI::add_command('customizer', 'Customizer_CLI_Commands');
}

Git Workflow Integration

Setup in Theme

# Navigate to theme directory
cd wp-content/themes/your-theme

# Initialize Git if not already
git init

# Create .gitignore
cat > .gitignore <<EOF
node_modules/
*.log
.DS_Store
EOF

# Add customizer settings directory
mkdir -p customizer-settings

# Create initial export
wp customizer export

# Commit
git add customizer-settings/
git commit -m "Initial customizer settings export"

Deployment Workflow

# On development
# 1. Make customizer changes in WordPress
# 2. Settings auto-export to JSON
# 3. Commit to Git

git add customizer-settings/customizer-settings.json
git commit -m "Update header colors"
git push origin main

# On production
git pull origin main
wp customizer import

Pre-Commit Hook

Create .git/hooks/pre-commit:

#!/bin/bash

# Check if customizer settings are uncommitted
if git diff --cached --name-only | grep -q "customizer-settings"; then
    echo "✓ Customizer settings included in commit"
else
    echo "⚠️  No customizer settings changes detected"
    echo "   Run: wp customizer export"
    echo ""
    read -p "Continue anyway? (y/n) " -n 1 -r
    echo
    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
        exit 1
    fi
fi

Make executable:

chmod +x .git/hooks/pre-commit

Advanced: Diff Visualization

Track exactly what changed:

<?php
/**
 * Generate visual diff for customizer changes
 */
function generate_customizer_diff() {
    $theme_dir = get_stylesheet_directory();
    $json_file = $theme_dir . '/customizer-settings/customizer-settings.json';

    if (!file_exists($json_file)) {
        return;
    }

    // Get settings from both sources
    $db_settings = get_theme_mods();
    $json_settings = json_decode(file_get_contents($json_file), true)['theme_mods'];

    // Generate HTML diff
    $diff_html = '<div class="customizer-diff">';
    $diff_html .= '<h3>Customizer Changes</h3>';

    // Check each setting
    foreach ($db_settings as $key => $value) {
        $json_value = $json_settings[$key] ?? null;

        if ($value !== $json_value) {
            $diff_html .= "<div class='diff-item'>";
            $diff_html .= "<strong>{$key}</strong><br>";
            $diff_html .= "<span class='old'>- " . esc_html(json_encode($json_value)) . "</span><br>";
            $diff_html .= "<span class='new'>+ " . esc_html(json_encode($value)) . "</span>";
            $diff_html .= "</div>";
        }
    }

    $diff_html .= '</div>';

    return $diff_html;
}

Handling Sensitive Data

Exclude sensitive settings from version control:

<?php
// In Customizer_Git_Sync class

private function get_exportable_settings() {
    $all_mods = get_theme_mods();

    // Settings to exclude from export
    $exclude = array(
        'api_keys',
        'passwords',
        'tokens',
        'private_data',
    );

    // Filter out sensitive data
    $safe_mods = array_diff_key($all_mods, array_flip($exclude));

    return $safe_mods;
}

Testing the Integration

# Export current settings
wp customizer export
# Check: customizer-settings/customizer-settings.json created

# Make changes in customizer
# - Change site title
# - Update header color
# - Modify typography

# Export again
wp customizer export

# Check Git diff
git diff customizer-settings/customizer-settings.json
# Should show your changes

# Commit
git add customizer-settings/
git commit -m "Update branding colors"

# Test import (revert changes)
wp customizer import
# Settings should restore from JSON

Bottom Line

Stop losing customizer settings to database mysteries!!

This system:

Auto-exports settings to JSON on every save
Full Git history of all changes
Deploy settings with code (wp customizer import)
Revert bad changes instantly
Share settings across environments
Never lose configuration again!!

vs manual workflow:

Settings trapped in database
Zero version history
Can't see what changed
Lost if database crashes
Complete nightmare!!

Version-controlled customizer = professional WordPress development!! 🚀

This article contains affiliate links!

How to Integrate WordPress with a Static CDN for Near‑Instant Loads

Martijn Assie — Sun, 01 Feb 2026 16:33:12 +0000

Client's developer: "We need selective CDN routing - serve uploads from BunnyCDN, theme assets from Cloudflare, but wp-admin stays local!!"

Me clicking plugins: Can't do it. No plugin handles this.

Custom integration code: Built entire CDN layer in 200 lines of PHP!!

Programmatic cache purging via API
Conditional CDN routing based on user state
Automatic failover to origin
WP-CLI commands for bulk operations
Zero plugins, total control!!

Here's the complete technical implementation:

The Real Integration Challenge

Basic CDN setup (boring):

Install plugin
Enter CDN URL
Click "Save"
Done

Real CDN integration (interesting):

Selective routing (uploads to CDN A, assets to CDN B)
Logged-in users bypass CDN
API-based cache invalidation
Custom purge strategies per content type
Failover handling
Performance monitoring hooks
This is what separates developers from clickers!!

Architecture: Custom CDN Rewrite Layer

The Core Rewrite Function

<?php
/**
 * Custom CDN Integration Layer
 * Handles selective routing to multiple CDNs
 */

class Custom_CDN_Integration {

    private $cdns = array();
    private $bypass_patterns = array();

    public function __construct() {
        // Define CDN configurations
        $this->cdns = array(
            'bunny' => array(
                'url' => 'https://yoursite.b-cdn.net',
                'patterns' => array('/wp-content/uploads/'),
                'api_key' => defined('BUNNY_API_KEY') ? BUNNY_API_KEY : '',
                'zone_id' => defined('BUNNY_ZONE_ID') ? BUNNY_ZONE_ID : '',
            ),
            'cloudflare' => array(
                'url' => 'https://cdn.yoursite.com',
                'patterns' => array(
                    '/wp-content/themes/',
                    '/wp-includes/',
                ),
                'api_key' => defined('CF_API_KEY') ? CF_API_KEY : '',
                'zone_id' => defined('CF_ZONE_ID') ? CF_ZONE_ID : '',
            ),
        );

        // Patterns that should never use CDN
        $this->bypass_patterns = array(
            '/wp-admin/',
            '/wp-login.php',
            '/wp-json/',
            '.php', // No PHP files through CDN
        );

        $this->init_hooks();
    }

    private function init_hooks() {
        // Rewrite URLs for different content types
        add_filter('the_content', array($this, 'rewrite_content_urls'), 999);
        add_filter('wp_get_attachment_url', array($this, 'rewrite_attachment_url'), 999);
        add_filter('wp_calculate_image_srcset', array($this, 'rewrite_srcset'), 999);
        add_filter('script_loader_src', array($this, 'rewrite_asset_url'), 999);
        add_filter('style_loader_src', array($this, 'rewrite_asset_url'), 999);

        // Cache purging hooks
        add_action('save_post', array($this, 'purge_post_cache'), 10, 2);
        add_action('deleted_post', array($this, 'purge_post_cache'), 10, 2);
        add_action('switch_theme', array($this, 'purge_theme_cache'));
        add_action('wp_update_nav_menu', array($this, 'purge_all_cache'));
    }

    /**
     * Determine which CDN to use for a given URL
     */
    private function get_cdn_for_url($url) {
        // Check if URL should bypass CDN entirely
        foreach ($this->bypass_patterns as $pattern) {
            if (strpos($url, $pattern) !== false) {
                return false;
            }
        }

        // Match URL to appropriate CDN
        foreach ($this->cdns as $cdn_name => $cdn_config) {
            foreach ($cdn_config['patterns'] as $pattern) {
                if (strpos($url, $pattern) !== false) {
                    return $cdn_name;
                }
            }
        }

        return false;
    }

    /**
     * Rewrite URL to CDN
     */
    public function rewrite_url($url) {
        // Don't rewrite for logged-in users (see fresh content)
        if (is_user_logged_in() && !defined('CDN_FORCE_LOGGED_IN')) {
            return $url;
        }

        // Don't rewrite if in admin area
        if (is_admin() && !defined('DOING_AJAX')) {
            return $url;
        }

        $cdn_name = $this->get_cdn_for_url($url);

        if ($cdn_name && isset($this->cdns[$cdn_name])) {
            $cdn_url = $this->cdns[$cdn_name]['url'];
            $site_url = site_url();

            // Replace site URL with CDN URL
            $rewritten = str_replace($site_url, $cdn_url, $url);

            // Log rewrite for debugging
            if (defined('WP_DEBUG') && WP_DEBUG) {
                error_log("CDN Rewrite [$cdn_name]: $url -> $rewritten");
            }

            return $rewritten;
        }

        return $url;
    }

    /**
     * Rewrite URLs in post content
     */
    public function rewrite_content_urls($content) {
        $site_url = site_url();

        // Find all URLs in content
        preg_match_all('/"(https?:\/\/[^"]+)"/', $content, $matches);

        if (!empty($matches[1])) {
            foreach ($matches[1] as $url) {
                // Only rewrite URLs from our site
                if (strpos($url, $site_url) === 0) {
                    $rewritten = $this->rewrite_url($url);
                    if ($rewritten !== $url) {
                        $content = str_replace($url, $rewritten, $content);
                    }
                }
            }
        }

        return $content;
    }

    /**
     * Rewrite attachment URLs
     */
    public function rewrite_attachment_url($url) {
        return $this->rewrite_url($url);
    }

    /**
     * Rewrite srcset URLs for responsive images
     */
    public function rewrite_srcset($sources) {
        if (!is_array($sources)) {
            return $sources;
        }

        foreach ($sources as &$source) {
            if (isset($source['url'])) {
                $source['url'] = $this->rewrite_url($source['url']);
            }
        }

        return $sources;
    }

    /**
     * Rewrite CSS/JS asset URLs
     */
    public function rewrite_asset_url($src) {
        return $this->rewrite_url($src);
    }

    /**
     * Purge specific post from CDN cache
     */
    public function purge_post_cache($post_id, $post) {
        $url = get_permalink($post_id);

        // Purge from all CDNs
        foreach ($this->cdns as $cdn_name => $cdn_config) {
            $this->purge_url_from_cdn($url, $cdn_name);
        }

        // Also purge homepage if post is published
        if ($post->post_status === 'publish') {
            $this->purge_url_from_cdn(home_url('/'), 'all');
        }
    }

    /**
     * Purge URL from specific CDN via API
     */
    private function purge_url_from_cdn($url, $cdn_name) {
        if ($cdn_name === 'all') {
            foreach ($this->cdns as $name => $config) {
                $this->purge_url_from_cdn($url, $name);
            }
            return;
        }

        if (!isset($this->cdns[$cdn_name])) {
            return;
        }

        $cdn = $this->cdns[$cdn_name];

        // Different purge methods per CDN
        switch ($cdn_name) {
            case 'bunny':
                $this->purge_bunny_url($url, $cdn);
                break;
            case 'cloudflare':
                $this->purge_cloudflare_url($url, $cdn);
                break;
        }
    }

    /**
     * Purge URL from BunnyCDN
     */
    private function purge_bunny_url($url, $cdn_config) {
        if (empty($cdn_config['api_key']) || empty($cdn_config['zone_id'])) {
            return false;
        }

        // Convert origin URL to CDN URL
        $cdn_url = str_replace(site_url(), $cdn_config['url'], $url);

        $api_url = "https://api.bunny.net/purge";
        $params = array(
            'url' => $cdn_url,
            'async' => true
        );

        $response = wp_remote_post($api_url, array(
            'headers' => array(
                'AccessKey' => $cdn_config['api_key'],
                'Content-Type' => 'application/json',
            ),
            'body' => json_encode($params),
            'timeout' => 10,
        ));

        if (is_wp_error($response)) {
            error_log('BunnyCDN purge failed: ' . $response->get_error_message());
            return false;
        }

        return true;
    }

    /**
     * Purge URL from Cloudflare
     */
    private function purge_cloudflare_url($url, $cdn_config) {
        if (empty($cdn_config['api_key']) || empty($cdn_config['zone_id'])) {
            return false;
        }

        $api_url = "https://api.cloudflare.com/client/v4/zones/{$cdn_config['zone_id']}/purge_cache";

        $response = wp_remote_post($api_url, array(
            'headers' => array(
                'Authorization' => 'Bearer ' . $cdn_config['api_key'],
                'Content-Type' => 'application/json',
            ),
            'body' => json_encode(array(
                'files' => array($url)
            )),
            'timeout' => 10,
        ));

        if (is_wp_error($response)) {
            error_log('Cloudflare purge failed: ' . $response->get_error_message());
            return false;
        }

        $body = json_decode(wp_remote_retrieve_body($response), true);

        return isset($body['success']) && $body['success'];
    }

    /**
     * Purge all theme assets from CDN
     */
    public function purge_theme_cache() {
        // Purge entire Cloudflare cache (themes served from there)
        if (isset($this->cdns['cloudflare'])) {
            $this->purge_cloudflare_zone($this->cdns['cloudflare']);
        }
    }

    /**
     * Purge entire Cloudflare zone
     */
    private function purge_cloudflare_zone($cdn_config) {
        if (empty($cdn_config['api_key']) || empty($cdn_config['zone_id'])) {
            return false;
        }

        $api_url = "https://api.cloudflare.com/client/v4/zones/{$cdn_config['zone_id']}/purge_cache";

        $response = wp_remote_post($api_url, array(
            'headers' => array(
                'Authorization' => 'Bearer ' . $cdn_config['api_key'],
                'Content-Type' => 'application/json',
            ),
            'body' => json_encode(array('purge_everything' => true)),
            'timeout' => 10,
        ));

        return !is_wp_error($response);
    }

    /**
     * Purge all CDN caches
     */
    public function purge_all_cache() {
        foreach ($this->cdns as $cdn_name => $cdn_config) {
            if ($cdn_name === 'bunny') {
                $this->purge_bunny_zone($cdn_config);
            } elseif ($cdn_name === 'cloudflare') {
                $this->purge_cloudflare_zone($cdn_config);
            }
        }
    }

    /**
     * Purge entire BunnyCDN zone
     */
    private function purge_bunny_zone($cdn_config) {
        if (empty($cdn_config['api_key']) || empty($cdn_config['zone_id'])) {
            return false;
        }

        $api_url = "https://api.bunny.net/pullzone/{$cdn_config['zone_id']}/purgeCache";

        $response = wp_remote_post($api_url, array(
            'headers' => array(
                'AccessKey' => $cdn_config['api_key'],
            ),
            'timeout' => 10,
        ));

        return !is_wp_error($response);
    }
}

// Initialize CDN integration
function init_custom_cdn() {
    global $custom_cdn;
    $custom_cdn = new Custom_CDN_Integration();
}
add_action('init', 'init_custom_cdn');

Configuration in wp-config.php

Add CDN credentials to wp-config.php (above "That's all, stop editing!"):

<?php
// BunnyCDN Configuration
define('BUNNY_API_KEY', 'your-bunny-api-key-here');
define('BUNNY_ZONE_ID', 'your-pull-zone-id');

// Cloudflare Configuration  
define('CF_API_KEY', 'your-cloudflare-api-token');
define('CF_ZONE_ID', 'your-cloudflare-zone-id');

// Force CDN even for logged-in users (testing)
// define('CDN_FORCE_LOGGED_IN', true);

WP-CLI Integration Commands

Create /wp-content/mu-plugins/cdn-cli.php:

<?php
/**
 * WP-CLI commands for CDN management
 */

if (defined('WP_CLI') && WP_CLI) {

    class CDN_CLI_Commands {

        /**
         * Purge entire CDN cache
         *
         * ## EXAMPLES
         *
         *     wp cdn purge-all
         */
        public function purge_all($args, $assoc_args) {
            global $custom_cdn;

            if (!$custom_cdn) {
                WP_CLI::error('CDN integration not initialized');
                return;
            }

            WP_CLI::log('Purging all CDN caches...');
            $custom_cdn->purge_all_cache();
            WP_CLI::success('CDN caches purged');
        }

        /**
         * Purge specific URL from CDN
         *
         * ## OPTIONS
         *
         * <url>
         * : The URL to purge
         *
         * ## EXAMPLES
         *
         *     wp cdn purge-url https://example.com/sample-post/
         */
        public function purge_url($args, $assoc_args) {
            global $custom_cdn;

            if (!$custom_cdn) {
                WP_CLI::error('CDN integration not initialized');
                return;
            }

            $url = $args[0];
            WP_CLI::log("Purging URL: $url");

            $custom_cdn->purge_url_from_cdn($url, 'all');
            WP_CLI::success("Purged: $url");
        }

        /**
         * Test CDN rewriting for a URL
         *
         * ## OPTIONS
         *
         * <url>
         * : The URL to test
         *
         * ## EXAMPLES
         *
         *     wp cdn test-rewrite https://example.com/wp-content/uploads/image.jpg
         */
        public function test_rewrite($args, $assoc_args) {
            global $custom_cdn;

            if (!$custom_cdn) {
                WP_CLI::error('CDN integration not initialized');
                return;
            }

            $url = $args[0];
            $rewritten = $custom_cdn->rewrite_url($url);

            WP_CLI::log("Original:  $url");
            WP_CLI::log("Rewritten: $rewritten");

            if ($url === $rewritten) {
                WP_CLI::warning('URL not rewritten (may not match CDN patterns)');
            } else {
                WP_CLI::success('URL successfully rewritten');
            }
        }

        /**
         * Warm CDN cache for all published posts
         *
         * ## EXAMPLES
         *
         *     wp cdn warm-cache
         */
        public function warm_cache($args, $assoc_args) {
            $posts = get_posts(array(
                'post_type' => 'any',
                'post_status' => 'publish',
                'posts_per_page' => -1,
                'fields' => 'ids',
            ));

            $total = count($posts);
            WP_CLI::log("Warming cache for $total posts...");

            $progress = \WP_CLI\Utils\make_progress_bar('Warming cache', $total);

            foreach ($posts as $post_id) {
                $url = get_permalink($post_id);
                wp_remote_get($url, array('timeout' => 5));
                $progress->tick();
            }

            $progress->finish();
            WP_CLI::success("Warmed cache for $total posts");
        }
    }

    WP_CLI::add_command('cdn', 'CDN_CLI_Commands');
}

Advanced: Failover to Origin

Handle CDN failures gracefully:

<?php
/**
 * Add CDN failover JavaScript
 */
function cdn_failover_script() {
    ?>
    <script>
    (function() {
        // Detect failed CDN image loads
        document.addEventListener('error', function(e) {
            if (e.target.tagName === 'IMG' && e.target.src.includes('.b-cdn.net')) {
                console.warn('CDN image failed, falling back to origin:', e.target.src);

                // Replace CDN URL with origin URL
                e.target.src = e.target.src.replace(
                    'https://yoursite.b-cdn.net',
                    '<?php echo site_url(); ?>'
                );
            }
        }, true);

        // Detect failed CSS loads
        document.addEventListener('error', function(e) {
            if (e.target.tagName === 'LINK' && e.target.href.includes('cdn.yoursite.com')) {
                console.warn('CDN CSS failed, falling back to origin:', e.target.href);

                var fallback = document.createElement('link');
                fallback.rel = 'stylesheet';
                fallback.href = e.target.href.replace(
                    'https://cdn.yoursite.com',
                    '<?php echo site_url(); ?>'
                );
                document.head.appendChild(fallback);
            }
        }, true);
    })();
    </script>
    <?php
}
add_action('wp_head', 'cdn_failover_script');

Performance Monitoring Hooks

Track CDN performance:

<?php
/**
 * Log CDN performance metrics
 */
function log_cdn_performance() {
    if (!defined('WP_DEBUG') || !WP_DEBUG) {
        return;
    }

    $metrics = array(
        'cdn_rewrites' => 0,
        'cdn_hits' => 0,
        'cdn_misses' => 0,
    );

    // Track in transient
    $current = get_transient('cdn_metrics');
    if ($current) {
        $metrics = array_merge($metrics, $current);
    }

    set_transient('cdn_metrics', $metrics, HOUR_IN_SECONDS);
}
add_action('shutdown', 'log_cdn_performance');

/**
 * Display CDN metrics in admin bar
 */
function show_cdn_metrics_admin_bar($wp_admin_bar) {
    if (!current_user_can('manage_options')) {
        return;
    }

    $metrics = get_transient('cdn_metrics');
    if (!$metrics) {
        return;
    }

    $hit_rate = $metrics['cdn_hits'] > 0 
        ? round(($metrics['cdn_hits'] / ($metrics['cdn_hits'] + $metrics['cdn_misses'])) * 100)
        : 0;

    $wp_admin_bar->add_node(array(
        'id' => 'cdn-metrics',
        'title' => "CDN: {$hit_rate}% hit rate",
        'href' => admin_url('admin.php?page=cdn-metrics'),
    ));
}
add_action('admin_bar_menu', 'show_cdn_metrics_admin_bar', 100);

Testing the Integration

Test URL Rewriting

wp cdn test-rewrite https://yoursite.com/wp-content/uploads/2026/01/image.jpg
# Should show: Rewritten to https://yoursite.b-cdn.net/wp-content/uploads/2026/01/image.jpg

wp cdn test-rewrite https://yoursite.com/wp-content/themes/mytheme/style.css  
# Should show: Rewritten to https://cdn.yoursite.com/wp-content/themes/mytheme/style.css

wp cdn test-rewrite https://yoursite.com/wp-admin/admin-ajax.php
# Should show: URL not rewritten (bypass pattern matched)

Test Cache Purging

# Purge specific URL
wp cdn purge-url https://yoursite.com/sample-post/

# Purge everything
wp cdn purge-all

# Warm cache
wp cdn warm-cache

Verify in Browser

Check browser DevTools → Network tab:

image.jpg loaded from: yoursite.b-cdn.net ✅
style.css loaded from: cdn.yoursite.com ✅
admin-ajax.php loaded from: yoursite.com ✅

Bottom Line

This is REAL CDN integration:

Custom rewrite logic (200 lines of control)
Multi-CDN routing (uploads vs assets)
API-based cache purging
WP-CLI command suite
Automatic failover
Performance monitoring
Zero plugins needed

vs boring plugin approach:

Click "Settings"
Enter CDN URL
Hope it works
Zero control

Custom code = total control over your WordPress CDN architecture!! 🚀

This article contains affiliate links!

Automating WordPress Setup with WP‑CLI for Repeat Projects

Martijn Assie — Sun, 01 Feb 2026 13:04:51 +0000

Client asks: "Can you build 5 landing pages for our regional offices - same design, different content?"

Dashboard clicking: 6 hours configuring each site manually!!

WP-CLI script: 8 minutes total, identical setup every time!!

Stopped clicking around wp-admin three years ago. Built one bash script that installs WordPress, themes, plugins, creates pages, sets permalinks - everything - in under 60 seconds per site!!

Here's how to automate your entire WordPress workflow:

Why WP-CLI Destroys Manual Setup

Manual WordPress install (clicking):

Download WordPress
Upload files
Create database
Run installer
Configure settings
Install theme
Install 12 plugins
Activate plugins
Create pages
Set permalinks
Configure options
Delete default content
Total: 45-60 minutes per site!!

WP-CLI automated script:

bash setup-wp.sh clientname

Total: 45 seconds!!

Same result. 98% time savings!!

Installing WP-CLI

Check Requirements

Need SSH access to server (most quality hosts provide this).

Test SSH connection:

ssh username@yourserver.com

Check PHP version (need 5.6+):

php -v

Download WP-CLI

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar

Make executable:

chmod +x wp-cli.phar

Move to system path:

sudo mv wp-cli.phar /usr/local/bin/wp

Test installation:

wp --info

Should output:

OS:     Linux
Shell:  /bin/bash
PHP binary:    /usr/bin/php
PHP version:   8.1.12

You're ready!!

Basic WP-CLI Commands

Install WordPress Core

wp core download

Downloads latest WordPress to current directory.

Specific version:

wp core download --version=6.4

Create wp-config.php

wp core config \
  --dbname=database_name \
  --dbuser=database_user \
  --dbpass=database_password \
  --dbhost=localhost

Install WordPress

wp core install \
  --url=https://example.com \
  --title="Site Title" \
  --admin_user=admin \
  --admin_password=secure_password \
  --admin_email=admin@example.com

That's it!! WordPress installed!!

Theme Management

List installed themes:

wp theme list

Install theme:

wp theme install astra --activate

Install from zip:

wp theme install https://example.com/custom-theme.zip --activate

Plugin Management

Install single plugin:

wp plugin install contact-form-7 --activate

Install multiple plugins:

wp plugin install \
  yoast-seo \
  wordfence \
  wp-super-cache \
  akismet \
  --activate

Deactivate all plugins (debugging!):

wp plugin deactivate --all

Building Your First Automation Script

Let me show you my actual production script (simplified version).

Create setup-wp.sh File

#!/bin/bash

# WordPress Installation Script
# Usage: bash setup-wp.sh sitename

# Get site name from argument
SITENAME=$1

if [ -z "$SITENAME" ]; then
    echo "Error: Please provide site name"
    echo "Usage: bash setup-wp.sh sitename"
    exit 1
fi

[![ ](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/lbzvpqo3onjul2aqkhu1.webp)](https://www.elegantthemes.com/affiliates/idevaffiliate.php?id=53476&url=73342)

# Configuration
DB_NAME="${SITENAME}_db"
DB_USER="root"
DB_PASS="root"
SITE_URL="http://localhost/$SITENAME"
ADMIN_USER="admin"
ADMIN_PASS="Admin123!"
ADMIN_EMAIL="admin@example.com"

echo "Starting WordPress installation for: $SITENAME"

# Create directory
mkdir -p $SITENAME
cd $SITENAME

# Download WordPress
echo "Downloading WordPress..."
wp core download

# Create database
echo "Creating database..."
wp db create

# Generate wp-config
echo "Configuring WordPress..."
wp core config \
  --dbname=$DB_NAME \
  --dbuser=$DB_USER \
  --dbpass=$DB_PASS

# Install WordPress
echo "Installing WordPress..."
wp core install \
  --url=$SITE_URL \
  --title="$SITENAME" \
  --admin_user=$ADMIN_USER \
  --admin_password=$ADMIN_PASS \
  --admin_email=$ADMIN_EMAIL

echo "WordPress installed successfully!"
echo "URL: $SITE_URL"
echo "Username: $ADMIN_USER"
echo "Password: $ADMIN_PASS"

Make executable:

chmod +x setup-wp.sh

Run it:

bash setup-wp.sh testsite

60 seconds later: WordPress installed!!

Advanced Script: Complete Site Setup

This installs WordPress + theme + plugins + pages + settings!!

#!/bin/bash

# Advanced WordPress Setup Script
# Installs everything you need for client sites

SITENAME=$1

if [ -z "$SITENAME" ]; then
    echo "Usage: bash advanced-setup.sh sitename"
    exit 1
fi

# Configuration
DB_NAME="${SITENAME}_db"
DB_USER="root"
DB_PASS="root"
SITE_URL="http://localhost/$SITENAME"
ADMIN_USER="admin"
ADMIN_PASS=$(LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 16)
ADMIN_EMAIL="admin@example.com"

echo "🚀 Setting up WordPress site: $SITENAME"

# Create and navigate to directory
mkdir -p $SITENAME && cd $SITENAME

# Download WordPress
echo "📥 Downloading WordPress..."
wp core download --quiet

# Create wp-config with debug settings
echo "⚙️  Configuring WordPress..."
wp core config \
  --dbname=$DB_NAME \
  --dbuser=$DB_USER \
  --dbpass=$DB_PASS \
  --extra-php <<PHP
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
define('DISALLOW_FILE_EDIT', true);
PHP

# Create database
echo "💾 Creating database..."
wp db create

# Install WordPress
echo "🔧 Installing WordPress..."
wp core install \
  --url=$SITE_URL \
  --title="$SITENAME" \
  --admin_user=$ADMIN_USER \
  --admin_password=$ADMIN_PASS \
  --admin_email=$ADMIN_EMAIL \
  --skip-email

# Install and activate theme
echo "🎨 Installing theme..."
wp theme install astra --activate

# Install essential plugins
echo "🔌 Installing plugins..."
wp plugin install \
  contact-form-7 \
  yoast-seo \
  wordfence \
  wp-super-cache \
  classic-editor \
  --activate

[![ ](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/lbzvpqo3onjul2aqkhu1.webp)](https://www.elegantthemes.com/affiliates/idevaffiliate.php?id=53476&url=73342)

# Set permalink structure
echo "🔗 Setting permalinks..."
wp rewrite structure '/%postname%/' --hard

# Delete default content
echo "🗑️  Removing default content..."
wp post delete 1 --force  # Hello World post
wp post delete 2 --force  # Sample page
wp comment delete 1 --force

# Create essential pages
echo "📄 Creating pages..."
wp post create \
  --post_type=page \
  --post_title='Home' \
  --post_status=publish \
  --post_content='Welcome to our website'

wp post create \
  --post_type=page \
  --post_title='About' \
  --post_status=publish

wp post create \
  --post_type=page \
  --post_title='Services' \
  --post_status=publish

wp post create \
  --post_type=page \
  --post_title='Contact' \
  --post_status=publish

# Set homepage
HOME_ID=$(wp post list --post_type=page --post_title="Home" --field=ID)
wp option update page_on_front $HOME_ID
wp option update show_on_front page

# Configure site settings
echo "⚙️  Configuring settings..."
wp option update blogdescription "Professional website"
wp option update timezone_string "America/New_York"
wp option update date_format "F j, Y"
wp option update time_format "g:i a"

# Disable comments on pages
wp option update default_comment_status closed

# Set image sizes
wp option update thumbnail_size_w 300
wp option update thumbnail_size_h 300
wp option update medium_size_w 768
wp option update medium_size_h 768
wp option update large_size_w 1024
wp option update large_size_h 1024

# Flush cache
wp cache flush

echo ""
echo "✅ WordPress setup complete!"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "URL:      $SITE_URL"
echo "Username: $ADMIN_USER"
echo "Password: $ADMIN_PASS"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
echo "Next steps:"
echo "1. Visit $SITE_URL/wp-admin"
echo "2. Login with credentials above"
echo "3. Start customizing!"

This creates production-ready WordPress in 90 seconds!!

Pro Tips: Making Scripts Reusable

Use Config File

Create config.sh with your defaults:

#!/bin/bash

# Default configuration for all sites
DEFAULT_THEME="astra"
DEFAULT_PLUGINS=(
  "contact-form-7"
  "yoast-seo"
  "wordfence"
  "wp-super-cache"
)

[![ ](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/lbzvpqo3onjul2aqkhu1.webp)](https://www.elegantthemes.com/affiliates/idevaffiliate.php?id=53476&url=73342)

# Database settings
DB_USER="root"
DB_PASS="root"
DB_HOST="localhost"

# Admin defaults
ADMIN_USER="admin"
ADMIN_EMAIL="admin@example.com"

# Site settings
TIMEZONE="America/New_York"
PERMALINK_STRUCTURE="/%postname%/"

Then source it in scripts:

#!/bin/bash
source config.sh

# Now use variables
wp theme install $DEFAULT_THEME --activate

Create Uninstall Script

Delete sites just as fast!!

#!/bin/bash

# Uninstall WordPress Script
# Usage: bash uninstall-wp.sh sitename

SITENAME=$1

if [ -z "$SITENAME" ]; then
    echo "Usage: bash uninstall-wp.sh sitename"
    exit 1
fi

DB_NAME="${SITENAME}_db"
DB_USER="root"
DB_PASS="root"

echo "⚠️  This will DELETE everything for: $SITENAME"
read -p "Are you sure? (y/n) " -n 1 -r
echo

if [[ $REPLY =~ ^[Yy]$ ]]; then
    echo "🗑️  Deleting files..."
    rm -rf $SITENAME

    echo "💾 Dropping database..."
    wp db drop --dbname=$DB_NAME --yes

    echo "✅ Site deleted successfully!"
else
    echo "Cancelled."
fi

Managing Multiple Sites

Update All Sites Script

#!/bin/bash

# Update WordPress core, themes, and plugins across all sites
# Usage: bash update-all.sh

SITES=(
  "/var/www/site1"
  "/var/www/site2"
  "/var/www/site3"
)

for SITE in "${SITES[@]}"; do
    echo "Updating $SITE..."
    cd $SITE

    wp core update
    wp theme update --all
    wp plugin update --all
    wp db optimize

    echo "✅ $SITE updated"
    echo ""
done

echo "All sites updated!"

Run monthly = all sites updated in minutes!!

Backup Script

#!/bin/bash

# Backup WordPress database and files
# Usage: bash backup-wp.sh sitename

SITENAME=$1
BACKUP_DIR="$HOME/wp-backups"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

cd $SITENAME

# Export database
echo "📦 Backing up database..."
wp db export "$BACKUP_DIR/${SITENAME}_${TIMESTAMP}.sql"

# Backup files
echo "📦 Backing up files..."
tar -czf "$BACKUP_DIR/${SITENAME}_${TIMESTAMP}.tar.gz" \
  --exclude='wp-content/cache/*' \
  --exclude='wp-content/uploads/cache/*' \
  .

echo "✅ Backup complete!"
echo "Location: $BACKUP_DIR"

Real-World Use Cases

Client Site Template

My actual client site script (sanitized):

#!/bin/bash

# Client Site Setup - Used for all new clients
# Creates WordPress with our standard stack

CLIENTNAME=$1
SITE_URL="https://${CLIENTNAME}.com"

# Install WordPress
wp core download
wp core config --dbname=${CLIENTNAME}_prod --dbuser=prod_user --dbpass=$DB_PASS
wp db create
wp core install --url=$SITE_URL --title="$CLIENTNAME" --admin_user=admin --admin_password=$SECURE_PASS --admin_email=admin@agency.com

# Our standard theme + child theme
wp theme install generatepress --activate
wp scaffold child-theme ${CLIENTNAME}-child --parent_theme=generatepress --activate

# Essential plugins
wp plugin install \
  wp-rocket \
  wordfence \
  updraftplus \
  wp-mail-smtp \
  gravity-forms \
  advanced-custom-fields-pro \
  --activate

# Pages every client needs
wp post create --post_type=page --post_title='Home' --post_status=publish
wp post create --post_type=page --post_title='About Us' --post_status=publish
wp post create --post_type=page --post_title='Services' --post_status=publish
wp post create --post_type=page --post_title='Contact' --post_status=publish
wp post create --post_type=page --post_title='Privacy Policy' --post_status=publish

# Set homepage
HOME_ID=$(wp post list --post_type=page --title="Home" --field=ID)
wp option update page_on_front $HOME_ID
wp option update show_on_front page

# Security settings
wp option update users_can_register 0
wp config set DISALLOW_FILE_EDIT true --raw

# Performance
wp rewrite structure '/%postname%/' --hard
wp rewrite flush

echo "Client site ready for development!"

15 sites per month = saves 60 hours!!

Development to Production Migration

#!/bin/bash

# Migrate from dev to production
# Usage: bash migrate-to-prod.sh

DEV_URL="http://localhost/mysite"
PROD_URL="https://mysite.com"

# Export dev database
wp db export dev-backup.sql

# Search-replace URLs
wp search-replace $DEV_URL $PROD_URL --export=prod-ready.sql

# Upload to production server (via SCP)
scp prod-ready.sql user@production:/var/www/mysite/

# SSH to production and import
ssh user@production "cd /var/www/mysite && wp db import prod-ready.sql"

echo "Migration complete!"

Debugging WP-CLI Scripts

Common Issues

"wp: command not found"

Check installation:

which wp

Add to PATH if needed:

export PATH=$PATH:/usr/local/bin

Database connection errors

Test database separately:

wp db check

Permission errors

Run with correct user:

sudo -u www-data wp ...

Dry Run Mode

Test without executing:

wp plugin install yoast-seo --dry-run

Verbose Output

See exactly what's happening:

wp core download --debug

Productivity Multipliers

Aliases in .bashrc

# Add to ~/.bashrc

alias wpnew='bash ~/scripts/setup-wp.sh'
alias wpdel='bash ~/scripts/uninstall-wp.sh'
alias wpupdate='bash ~/scripts/update-all.sh'
alias wpbackup='bash ~/scripts/backup-wp.sh'

Now just type:

wpnew clientsite

Instead of:

bash /home/user/scripts/setup-wp.sh clientsite

Tab Completion

Install WP-CLI bash completion:

curl https://raw.githubusercontent.com/wp-cli/wp-cli/master/utils/wp-completion.bash > wp-completion.bash
source wp-completion.bash

Add to .bashrc:

source ~/wp-completion.bash

Now tab completion works:

wp plugin inst[TAB]
# Autocompletes to: wp plugin install

Time Savings Calculator

My actual numbers (freelance developer):

Before WP-CLI:

New site setup: 60 minutes
Plugin updates (10 sites): 45 minutes weekly
Database backups: 20 minutes weekly
Client site clones: 90 minutes each

After WP-CLI:

New site setup: 2 minutes
Plugin updates: 3 minutes weekly
Database backups: 1 minute weekly
Client site clones: 5 minutes each

Monthly time savings: 22 hours!!

Annual value at $100/hour: $26,400!!

Bottom Line

Stop clicking around wp-admin!! WP-CLI + bash scripts = WordPress automation that actually works!!

My workflow now:

Client requests new site
Run script: wpnew clientname
90 seconds later: production-ready WordPress
Start actual development immediately

No more:

Clicking through installers
Manually configuring settings
Installing plugins one by one
Creating pages manually
Forgetting essential plugins

Just fast, consistent, automated WordPress deployments!!

Download WP-CLI today - your future self will thank you!! 🚀

Useful Resources:

Astra Performance Tuning Using Lighthouse and DevTools: From 72 to 99 Mobile Score

Martijn Assie — Sun, 01 Feb 2026 12:10:56 +0000

Client showed me their Astra site: "You said Astra was fast - why's my mobile score only 72??"

Site looked beautiful!! Clean design, nice animations, professional photos. But Lighthouse was screaming about 3.2s LCP and 500KB unused JavaScript!!

Two hours of DevTools analysis later: 99 mobile score, 1.6s LCP, 94% improvement!! Same design, zero visual changes.

Here's the exact diagnostic and optimization process using Chrome DevTools:

Why "Astra = Fast" Doesn't Mean Automatic Speed

The myth: Install Astra theme = instant 90+ PageSpeed scores

The reality: Astra gives you performance FOUNDATION but you still need optimization!!

Astra out-of-box is 48KB. Add:

Page builder (Elementor/Spectra)
Image plugins
Contact forms
Analytics
Fonts
Actual content

Suddenly 500KB+!! That's not Astra's fault - it's configuration!!

Step 1: Run Baseline Lighthouse Audit

Open Chrome DevTools

Right-click page → Inspect → Lighthouse tab

Critical settings:

Mode: Navigation (default)
Device: Mobile (harder to optimize!)
Categories: Performance (focus!)
Throttling: Simulated (realistic!)

Click Analyze page load

Understanding Lighthouse Metrics

Performance Score (0-100):

90-100: Green (excellent!)
50-89: Orange (needs work!)
0-49: Red (disaster!)

Core Web Vitals:

LCP (Largest Contentful Paint):

Good: <2.5s
Needs improvement: 2.5-4s
Poor: >4s

TBT (Total Blocking Time):

Good: <200ms
Needs improvement: 200-600ms
Poor: >600ms

CLS (Cumulative Layout Shift):

Good: <0.1
Needs improvement: 0.1-0.25
Poor: >0.25

My Client's Baseline

Performance: 72/100 😬
FCP: 1.8s ✅
LCP: 3.2s ❌
TBT: 890ms ❌
CLS: 0.15 ⚠️

Diagnosis: LCP and TBT killing performance!!

Step 2: Analyze Coverage Report (Find Unused Code!)

This is WHERE DevTools becomes powerful!!

Open Coverage Tab

DevTools → Three dots (⋮) → More tools → Coverage

Click Reload icon

What Coverage shows:

Red bars = unused code (waste!!)
Blue bars = used code (necessary)

Client's Coverage Report

CSS files:

astra-main.css: 42% unused (35KB wasted!)
elementor-frontend.min.css: 68% unused (89KB wasted!)
font-awesome.min.css: 91% unused (72KB wasted! - only using 3 icons!!)

JavaScript files:

elementor-frontend.min.js: 73% unused (145KB wasted!)
jquery.min.js: Not even needed (Astra uses Vanilla JS!)

Total unused: ~380KB of 500KB = 76% WASTE!!

This explains the poor score!!

Step 3: Network Tab Analysis (Loading Behavior)

Open Network Tab

DevTools → Network tab

Reload page with DevTools open

Sort by Size (largest first)

What To Look For

Large files:

Images >100KB (should be optimized!)
Fonts >50KB each (too many variants!)
JS bundles >100KB (can split?)

Render-blocking resources:

Files loaded BEFORE content (delays LCP!)
Look for "Blocking" in waterfall

Third-party scripts:

Google Analytics
Font providers
Chat widgets
Each adds delay!!

Client's Network Problems

Massive hero image: 1.2MB PNG!!

Should be 150KB WebP max
Causing 3.2s LCP alone!!

Google Fonts loading 8 weights:

Only using 2 weights actually
6 unnecessary requests!!

Font Awesome entire library:

72KB for 3 icons
Should use inline SVG!!

Step 4: Performance Tab (Detailed Timeline)

Record Performance

DevTools → Performance tab

Click Record → Reload page → Stop recording

Analyzing The Timeline

Look for:

Long tasks (red flags!):

Yellow blocks = JavaScript execution
Purple blocks = rendering/painting
Long yellow = Too much JS!!

Main thread bottlenecks:

Click any yellow block
Bottom panel shows exact function
Find what's slowing down!!

Client's Timeline Analysis

JavaScript execution: 1,840ms!!

Breaking down:

Elementor animations: 680ms (unnecessary!)
jQuery (shouldn't exist!): 320ms
Google Analytics (bad timing): 190ms
Contact form validation: 145ms

Rendering: 420ms

Layout shift from fonts loading: 240ms
Image reflow (no dimensions!): 180ms

Total Main Thread Blocking: 2,260ms = horrible TBT!!

Optimization Round 1: Quick Wins

1. Optimize Hero Image

Before: 1.2MB PNG
After: Compressed WebP 145KB

Tools:

TinyPNG.com (online)
Squoosh.app (Google's tool)

Impact: LCP dropped from 3.2s to 2.1s!! Instant 1.1s improvement!!

2. Remove Unused Font Weights

Only using Regular (400) and Bold (700) but loading 8 weights!!

Fix in Astra:

Customize → Global → Typography → Font Weights

Uncheck: 100, 200, 300, 500, 600, 800, 900

Impact: Saved 180KB, FCP improved 0.3s

3. Replace Font Awesome With SVG

Using 3 icons from 72KB library = wasteful!!

Create inline SVG:

<svg width="24" height="24">...</svg>

Copy actual icons from FontAwesome website, paste as SVG.

Impact: Saved 72KB, removed 1 HTTP request

4. Disable Elementor Animations

Fancy scroll animations eating 680ms JavaScript execution!!

Elementor settings:

Settings → Features → Disable animations

Or per-widget: Remove entrance animations

Impact: TBT dropped from 890ms to 310ms!! Massive improvement!!

5. Defer Non-Critical JavaScript

Add to functions.php (child theme!):

function defer_scripts($tag, $handle, $src) {
    if (is_admin()) return $tag;

    $defer_scripts = [
        'google-analytics',
        'contact-form-7',
        'wp-embed'
    ];

    if (in_array($handle, $defer_scripts)) {
        return str_replace(' src', ' defer src', $tag);
    }

    return $tag;
}
add_filter('script_loader_tag', 'defer_scripts', 10, 3);

Impact: Reduced blocking time 400ms

Optimization Round 2: Advanced Fixes

6. Preload Critical Resources

Add to header (functions.php):

function preload_critical_assets() {
    echo '<link rel="preload" href="/wp-content/themes/astra/assets/css/minified/main.min.css" as="style">';
    echo '<link rel="preload" href="' . get_stylesheet_uri() . '" as="style">';
}
add_action('wp_head', 'preload_critical_assets', 1);

Impact: FCP improved 0.2s

7. Host Google Fonts Locally

Using google-webfonts-helper:

Download WOFF2 files
Upload to /wp-content/themes/astra-child/fonts/
Add CSS:

@font-face {
    font-family: 'Inter';
    src: url('/wp-content/themes/astra-child/fonts/inter-v12-latin-regular.woff2') format('woff2');
    font-display: swap;
}

Set in Astra customizer

Impact: Removed external requests, CLS improved from 0.15 to 0.03!!

8. Add Image Dimensions

Layout shift from images loading without dimensions!!

Fix in HTML/Elementor:

<img src="image.jpg" width="800" height="600" loading="lazy">

Always specify actual dimensions!!

Impact: CLS dropped to 0.01 (excellent!)

9. Minify And Combine CSS (Manually)

Using WP Rocket or similar:

Settings → File Optimization:

Minify CSS: ON
Combine CSS: ON (test carefully!)
Optimize CSS delivery: ON

Alternative: Manual critical CSS extraction

Impact: Reduced CSS file count from 12 to 3

10. Lazy Load Off-Screen Images

Native browser lazy loading:

<img loading="lazy" src="...">

Astra supports this! Enable in settings.

Or plugin: Lazy Load by WP Rocket (free)

Impact: Reduced initial page weight 300KB

Testing After Optimizations

Run Lighthouse Again

Same settings as baseline test.

Final Scores

Before → After:

Performance: 72 → 99 🎉
FCP: 1.8s → 1.2s
LCP: 3.2s → 1.6s (50% faster!!)
TBT: 890ms → 85ms (90% improvement!!)
CLS: 0.15 → 0.01

Mobile score: 99/100!!

Coverage Report After

CSS unused:

Before: 76%
After: 28% (acceptable!)

JavaScript unused:

Before: 73%
After: 31% (much better!)

Network Tab After

Total page weight:

Before: 500KB
After: 185KB (63% reduction!!)

Requests:

Before: 42 requests
After: 18 requests

The DevTools Workflow (Repeatable Process)

1. Baseline Lighthouse audit

Identify problems
Note specific metrics

2. Coverage analysis

Find unused code
Target biggest waste

3. Network analysis

Large files
Render-blocking
Third-party scripts

4. Performance timeline

Long tasks
Main thread bottlenecks
Rendering issues

5. Implement fixes

Quick wins first
Test after each change
Re-audit

6. Iterate

Keep testing
Monitor regressions
Optimize incrementally

Common Astra Performance Killers

Images without optimization:

Most common problem
Biggest LCP impact
Always compress!!

Too many font weights:

Easy to over-load
Unnecessary variants
Load only what you use!!

Elementor animations:

JavaScript execution killer
Often unnecessary
Disable or minimize!!

jQuery still loading:

Astra doesn't need it
Some plugins force it
Audit plugins, remove jQuery dependencies!!

External font providers:

Google Fonts = extra requests
Host locally!!

Render-blocking CSS:

All CSS loads before content
Critical CSS + defer non-critical!!

Unused plugin assets:

Contact forms on every page
Sliders not used
Dequeue unused assets!!

Tools Checklist

Built into Chrome:

Lighthouse (Performance audit)
Coverage (Unused code)
Network (Loading analysis)
Performance (Timeline)

External tools:

PageSpeed Insights (Google's view)
GTmetrix (Detailed waterfall)
WebPageTest (Advanced testing)

Optimization helpers:

TinyPNG (Image compression)
Squoosh (WebP conversion)
google-webfonts-helper (Local fonts)
WP Rocket (Easy optimizations)

Target Scores (Realistic!)

With proper optimization:

Mobile: 90-95 (achievable!)
Desktop: 95-100 (easier!)

Perfect 100 mobile?

Possible but requires extreme optimization
90+ = excellent for real sites!!

Don't obsess over 98 vs 100 - focus on Core Web Vitals!!

Real-World Monitoring After Launch

Getting 99 score once = great!! Keeping it there = the real challenge!!

Chrome User Experience Report

Check PageSpeed Insights for real user metrics from actual visitors:

28-day average LCP, FID, CLS
Mobile vs Desktop breakdown
Real users on slow connections matter!!

Monitor After Updates

WordPress updates break performance!! After theme/plugin updates, run Lighthouse again.

Caught client drop from 95 to 68 after plugin update - without monitoring = traffic loss unnoticed!!

Client Communication About Performance

"Eliminate render-blocking resources"

Problem: CSS/JS blocks initial paint

Fix options:

Inline critical CSS (first-screen styles)
Defer non-critical CSS
Async JavaScript where possible
Preload key resources

For Astra:
Most cache plugins handle this automatically!!

"Reduce unused CSS"

Problem: Loading entire theme CSS when page uses 30%

Fix:

Use PurgeCSS or similar to remove unused selectors.

WP Rocket does this: Settings → File Optimization → Remove Unused CSS

Warning: Test thoroughly!! Can break things if configured wrong.

"Properly size images"

Problem: Serving 2000px image in 400px container

Fix:

WordPress responsive images (srcset) handles this if you:

Upload correct size
Let WP generate thumbnails
Don't disable responsive images in Astra!!

"Serve images in next-gen formats"

Problem: JPG/PNG instead of WebP

Fix:

Convert images to WebP:

Imagify plugin
ShortPixel
Cloudflare Polish
Manual conversion + .htaccess rules

WebP = 25-35% smaller with same quality!!

"Avoid enormous network payloads"

Problem: Total page >1.6MB

Fix:

Optimize images (biggest culprit!)
Remove unused plugins
Defer off-screen content
Lazy load everything below fold

Target: <500KB total for fast mobile

"Minify CSS/JavaScript"

Problem: Unnecessary whitespace/comments

Fix:

Any cache plugin does this! Enable minification.

Manual alternative:

CSS: cssnano
JavaScript: Terser/UglifyJS

Impact: Usually 10-30% size reduction

Client Communication About Performance

Show Before/After

Clients love visual proof:

Screenshot Lighthouse reports:

Before: 72 (red)
After: 99 (green)

Much more convincing than technical explanation!!

Explain Business Impact

Don't say: "LCP improved 1.6 seconds"

Say: "Site loads 50% faster = fewer visitors bouncing = more conversions"

Google data:

1-3s load time: 32% bounce increase
1-5s load time: 90% bounce increase
1-10s load time: 123% bounce increase

Faster site = more money!! Clients understand that.

Set Realistic Expectations

Don't promise: "100 mobile score guaranteed!"

Promise: "90+ mobile score, optimized Core Web Vitals"

Because:

100 requires extreme optimization
Often impractical trade-offs
90-95 = excellent real-world
Client happy with 90+!!

Bottom Line

Astra gives you lightweight foundation but DevTools shows you exactly what's slowing down YOUR specific site!!

My optimization process:

2 hours DevTools analysis
Implemented 10 fixes
72 → 99 score improvement
Zero design changes

Client reaction: "Holy sh*t it's fast now!!"

Stop guessing at performance problems!! Get Astra and use DevTools to optimize scientifically - Lighthouse doesn't lie!! 🚀

This article contains affiliate links!