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

Static analysis

TAW Theme ships phpstan.neon (level 5, Blocks/ and inc/ only) with WordPress core stubs via szepeviktor/phpstan-wordpress, so core functions/classes resolve correctly instead of erroring as unknown.

composer run phpstan

Runs automatically in CI on every push/PR. Prefer fixing types over adding ignoreErrors entries — see the wp-phpstan skill in WordPress/agent-skills for WordPress-specific typing patterns.

Direct field read/write — fields:get / fields:set

php bin/taw fields:get/fields:set read or write a single Metabox/OptionsPage field's value directly — the same primitive VisualEditorEndpoint uses for its REST-driven saves, exposed as a CLI command. The field's type is resolved from the live Metabox registry (the same one inspect reports), then dispatched to the matching type-aware getter/sanitizer, so a repeater comes back as a decoded array and gets sanitized exactly like a real admin form save — not a hand-rolled approximation.

php bin/taw fields:get 42 hero_heading --json
php bin/taw fields:get 42 team_members --json                        # repeater comes back as a decoded array

php bin/taw fields:set 42 hero_heading "Welcome"
php bin/taw fields:set 42 team_members --file=/tmp/team.json         # --file avoids shell JSON-quoting for repeater/array values
php bin/taw fields:set 42 hero_heading "Welcome" --dry-run           # preview the sanitized result without writing

This is the "populate the content" half of a design-to-page pipeline: figma-to-block/make-metablock scaffold the block and its empty fields, fields:set fills them in.

Content-writing safety model

fields:set itself has no interactive confirmation — it's a raw primitive, usable from scripts, not just an AI agent. All risk judgment belongs to whichever skill or agent calls it. The populate-content Claude Code skill (and the population step built into make-metablock/figma-to-block/build-page) follows a mandatory model: always --dry-run before a real write; always confirm before overwriting a non-empty existing value (old vs. new shown side by side); always confirm before writing to a publish-status post regardless of whether the field is empty; one confirmation for an entire batch plan, never silently expanded mid-batch; extra scrutiny on wysiwyg/'sanitize' => 'code' fields when the source content is external; never touches post_title/post_content/post_status, only Metabox/OptionsPage meta; no wildcard mass-edits — every affected post/field is enumerated up front.

See the AI Integration page for the full picture — skills, this safety model, inspect, WP-CLI, CI, and static analysis together.

WP-CLI — live site data access

bin/taw scaffolds, introspects, and (via fields:get/fields:set above) can now read/write individual field values — but it has no general-purpose view into site content beyond that. For posts, options, users, terms, transients, arbitrary PHP via wp eval/wp eval-file, or an interactive wp shell, use WordPress's own official CLI, WP-CLI (the wp command). It's a host-level tool, not bundled by this theme, but present on virtually every real WordPress host and every local dev environment (Local, Herd, DDEV).

Prefer php bin/taw wp <args> over a bare wp command — a thin passthrough (every argument forwarded exactly as given) that automatically resolves --path and, under Local by Flywheel, the per-site MySQL socket (see the Callout below) — no manual configuration needed:

php bin/taw wp post list --post_type=page --fields=ID,post_title,post_status
php bin/taw wp option get siteurl
php bin/taw wp eval 'echo home_url();'

ps aux | grep mysqld   # find the socket path for this site's mysqld — .../Local/run/<SITE_ID>/conf/mysql/my.cnf
SOCK="$HOME/Library/Application Support/Local/run/<SITE_ID>/mysql/mysqld.sock"
php -d mysqli.default_socket="$SOCK" -d pdo_mysql.default_socket="$SOCK" "$(which wp)" post list --path=/path/to/site/app/public

ViteLoader::isDevServerRunning() is safe under WP-CLI — the dev-server probe only runs on wp_enqueue_scripts, which doesn't fire for most wp commands. For general WP-CLI operations beyond this framework's scope, see the wp-wpcli-and-ops skill in WordPress/agent-skills.

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: