Theme boot and performance

When and how to boot the theme

Call TAW\Core\Theme::boot() once from your theme to wire up block loading, Vite assets, visual editor behavior, REST endpoints, and SVG support.

Theme::boot() hooks into core WordPress actions:

• On after_setup_theme, it:

  • Calls BlockLoader::loadAll() to register all TAW Core blocks.

  • Calls ViteLoader::init() to prepare your asset pipeline.

• On wp_enqueue_scripts, it:

  • Calls BlockRegistry::enqueueQueuedAssets() to enqueue CSS/JS requested by blocks during render.

  • Registers SearchEndpoints for the taw/v1/search-posts REST endpoint.

  • Calls Svg::register() to enable safe SVG upload and sanitization.

Recommended bootstrap flow

Set up your theme by booting TAW Core and then configuring performance. Use this flow in your functions.php (or equivalent) entry point.

<?php
// functions.php

require __DIR__ . '/vendor/autoload.php';

<?php

use TAW\Core\Theme;

Theme::boot();

<?php

use TAW\Core\Theme;

Theme::boot();

Theme::performance([
    'remove_bloat'        => true,
    'remove_emoji'        => true,
    'remove_meta_tags'    => true,
    'remove_oembed'       => true,
    'preconnect_origins'  => [
        'https://fonts.gstatic.com',
        'https://cdn.taw-assets.com',
    ],
    'preload_fonts'       => [
        'resources/fonts/inter-var.woff2',
    ],
    'preload_images'      => [
        // [attachment_id, size]
        [1234, 'hero-desktop'],
    ],
]);

Minimal functions.php example

For a clean theme that only uses the defaults and basic performance flags:

<?php
// functions.php

use TAW\Core\Theme;

Theme::boot();

Theme::performance([
    'remove_bloat'     => true,
    'remove_emoji'     => true,
    'remove_meta_tags' => true,
    'remove_oembed'    => true,
]);

Theme::boot([
    'performance' => [
        'remove_bloat'     => true,
        'remove_emoji'     => true,
        'remove_meta_tags' => true,
        'remove_oembed'    => true,
    ],
]);

You should now see your custom blocks available in the editor, Vite-powered assets loading on the front end, and unnecessary WordPress bloat removed from the page output.

Performance configuration reference

Theme::performance(array $config) accepts a keyed array and forwards it to Performance::configure(). All keys are optional; omit a key to leave the existing behavior unchanged.

Use these configuration options to strip unneeded WordPress features and add preload and preconnect hints.

Boolean flags

Resource hints and preloads

Template helpers you will use often

Once the theme is booted and performance is configured, use helper classes from the TAW\Helpers namespace to keep your templates concise and consistent.

Vite asset helpers (TAW\Support\ViteLoader)

ViteLoader is the OOP Vite bridge shipped in taw/core. It is PSR-4 autoloaded — no explicit include needed.

<?php

use TAW\Support\ViteLoader;

// Resolve a self-hosted font file
$fontUrl = ViteLoader::assetUrl('resources/fonts/Inter-Regular.woff2');

echo '<link rel="preload" href="' . esc_url($fontUrl) . '" as="font" crossorigin>';

<?php

use TAW\Support\ViteLoader;

if (ViteLoader::isDevServerRunning()) {
    // dev-only logic
}

TAW\Helpers\Image

TAW\Helpers\Image generates <img> tags with the correct loading, fetchpriority, decoding, srcset, and sizes attributes based on whether the image is above or below the fold.

• Render optimized <img> tags with proper performance attributes.

• Generate <link rel="preload"> tags for above-the-fold images.

• Work with WordPress attachment IDs rather than hard-coded URLs.

Use this helper in hero sections, featured images, and any template that must load quickly on first paint.

Commonly used methods

<?php

use TAW\Helpers\Image;

// Above-the-fold hero (eager, high priority)
echo Image::render($hero_id, 'full', ['above_fold' => true]);

// Regular image (lazy, low priority — the default)
echo Image::render(get_post_thumbnail_id(), 'large');

// With CSS class and custom sizes attribute
echo Image::render($id, 'large', [
    'class' => 'rounded-lg shadow-md',
    'sizes' => '(max-width: 768px) 100vw, 50vw',
]);

// With arbitrary extra attributes
echo Image::render($id, 'medium', [
    'attr' => ['id' => 'site-logo', 'data-hero' => 'true'],
]);

<?php

use TAW\Helpers\Image;

echo Image::preloadTag($hero_id, 'full');
// → <link rel="preload" href="..." as="image" imagesrcset="..." imagesizes="...">

TAW\Helpers\Svg

TAW\Helpers\Svg works together with Svg::register() from the theme boot process to:

• Allow safe SVG uploads and sanitize content.

• Render SVGs inline in your templates.

• Generate URLs to SVG assets managed by TAW Core.

Use this helper when you want sharp icons and logos without relying on raster images.

<?php

use TAW\Helpers\Svg;

// You normally do not need to call this manually because Theme::boot() handles it.
// Svg::register();

<?php

use TAW\Helpers\Svg;

echo Svg::render(5678, 'Company logo', [
    'class' => 'site-logo',
]);

<?php

use TAW\Helpers\Svg;

echo '<button class="icon-button">';
echo Svg::inline(9012, [
    'class' => 'icon icon-play',
]);
echo '</button>';

<?php

use TAW\Helpers\Svg;

$iconUrl = Svg::url(9012);

echo '.icon-custom { background-image: url(' . esc_url($iconUrl) . '); }';

Choosing between render and inline

Use Svg::render() when you want a simple <img> tag with an alt attribute and do not need to manipulate the SVG internals. Use Svg::inline() when you need CSS access to paths and groups or want to drive animations.

<?php

use TAW\Helpers\Svg;

// Standard logo as an <img> element.
echo Svg::render(5678, 'Header logo', [
    'class' => 'site-logo',
]);

// Inline SVG icon that inherits text color and can be animated.
echo Svg::inline(9012, [
    'class' => 'icon icon-arrow',
]);

Navigation menu registration

Menus are registered in functions.php via register_nav_menus(). Add or rename locations there directly, then assign menus to locations in WordPress Admin → Appearance → Menus.

// functions.php
register_nav_menus([
    'primary' => __('Primary Navigation', 'taw'),
    'footer'  => __('Footer Navigation', 'taw'),
]);

To render menus in templates, use TAW\Core\Menu\Menu::get($location). See the Navigation menus reference in the TAW Core tools overview for the full Menu and MenuItem API.

Boilerplate blocks

TAW Theme ships with ready-to-use blocks you can drop in immediately or treat as reference implementations when building your own.

Hero

Blocks/Hero/ is a full-featured MetaBlock that demonstrates the breadth of TAW Core's metabox field system. It serves both as a usable hero section and as a reference for advanced field patterns.

Registered fields:

• heading and tagline — text inputs (with a checkbox to toggle tagline visibility)
• content — wysiwyg rich text editor
• image — background image picker
• bg_color — color picker for section background
• padding — range slider (20–200 px, default 80 px)
• featured_post / related_posts — single and multi post_select fields
• team_members — repeater containing text, textarea, image, and a group for social URLs
• nested_repeater — three-level nested repeater demonstrating sub-nested data structures

The Hero block is the canonical reference for nested repeaters. Use it as a starting point when you need hierarchical repeater data in your own blocks.

Menu — site header with live search

Blocks/Menu/ is a two-row site header with a keyboard-accessible Alpine.js live-search overlay. It extends TAW\Core\Block (UI Block) and renders itself with no metabox configuration required.

// header.php
use TAW\Blocks\Menu\Menu;

(new Menu())->render();

What it includes:

• Top row — custom logo (or site name fallback), optional company address pulled from OptionsPage, and a search trigger button.
• Bottom row — primary nav menu with hover dropdowns for items that have children, plus optional company email and phone from OptionsPage.
• Search overlay — debounced live fetch against GET /wp-json/wp/v2/search, a results list, empty state, loading spinner, Escape-to-close, and body scroll lock.

The block reads company contact details (company_address, company_email, company_phone) directly from your OptionsPage settings, so those fields must be configured under TAW Settings in the admin for them to appear.

Restrict search to specific post types

Edit the subtype param in Blocks/Menu/script.js:

const params = new URLSearchParams({
    search: query,
    type: 'post',
    subtype: 'post,page', // ← adjust as needed
    per_page: 8,
});

Translate overlay labels

Edit the strings directly in Blocks/Menu/index.php:

• What are you looking for? — the overlay heading
• Search posts and pages… — the input placeholder

Framework updates

TAW Core is distributed as a Composer package (taw/core). To update the framework to the latest version, run:

composer update taw/core

Theme updates (auto-updater)

TAW\Core\ThemeUpdater (shipped in taw/core) hooks into WordPress's update system to check a GitHub Releases URL for new versions. When a newer release is found, the standard Update Available notice appears in the admin.

// functions.php
new TAW\Core\ThemeUpdater([
    'slug'       => 'taw-theme',
    'github_url' => 'https://api.github.com/repos/your-username/taw-theme/releases/latest',
]);

Updates are cached for 6 hours to avoid GitHub rate limits. The updater prefers a built ZIP asset in the release; falls back to GitHub's auto-generated zipball.

CSS Studio (dev-only visual editor)

CSS Studio is a browser-based visual editor that streams live-page edits directly to your AI coding assistant. It is pre-installed in TAW Theme.

Requires: Vite dev server running (npm run dev) and the toggle enabled in WP Admin.

Toggle: WP Admin → TAW Settings → Developer Tools → Enable CSS Studio

Start a session (inside Claude Code / your AI agent):

/studio

When active, every change you make in the visual panel — text edits, style tweaks, attribute changes — is sent to the agent as structured data and applied to the source files automatically. CSS Studio is injected only when the Vite dev server is active, so it never ships to production.

What to read next

Deepen your theme integration with these focused guides: