Quickstart

This guide builds a site on TAW Theme, the classic theme: PHP blocks with metabox fields, Vite, Tailwind and Alpine. For a block (full site editing) site, install TAW Gutenberg the same way and continue with TAW Gutenberg.

Before you start

Step 1 — Create the site

brew install Relmaur/tap/taw-fleet
taw-fleet create "Acme Shop" --classic

cd wp-content/themes

TAW_STARTER=theme composer create-project taw/create my-theme \
  --repository='{"type":"vcs","url":"https://github.com/Relmaur/taw-create"}'

cd my-theme
git init && git add -A && git commit -m "Initial commit"

Then push the theme to a new GitHub repository of its own, for example with gh repo create acme-shop --private --source=. --push. The theme shares no git history with the TAW Theme repository, and doesn't need to: framework updates arrive through taw/core, not through a merge.

Check that the taw command works:

taw list

Start Vite while you work. It serves CSS and JS with hot reload on port 5173:

npm run dev

Step 2 — Create your first block

TAW has two block types. For this quickstart we'll build a MetaBlock — a page section backed by metabox fields in the WordPress admin.

taw make:block Hero --type=meta --with-style
composer dump-autoload

Blocks/Hero/
├── Hero.php       ← the block class
├── index.php      ← the template
└── style.scss     ← per-block styles (auto-enqueued)

<?php
// Blocks/Hero/Hero.php

namespace TAW\Blocks\Hero;

use TAW\Core\Block\MetaBlock;
use TAW\Core\Metabox\Metabox;

class Hero extends MetaBlock
{
    protected string $id = 'hero';

    protected function registerMetaboxes(): void
    {
        new Metabox([
            'id'      => 'taw_hero',
            'title'   => 'Hero Section',
            'screens' => ['page'],
            'fields'  => [
                ['id' => 'hero_heading', 'label' => 'Heading', 'type' => 'text',     'required' => true],
                ['id' => 'hero_subtext', 'label' => 'Subtext', 'type' => 'textarea'],
                ['id' => 'hero_image',   'label' => 'Image',   'type' => 'image'],
            ],
        ]);
    }

    protected function getData(int|false $postId): array
    {
        return [
            'heading'   => $this->getMeta($postId, 'hero_heading'),
            'subtext'   => $this->getMeta($postId, 'hero_subtext'),
            'image_url' => $this->getImageUrl($postId, 'hero_image', 'large'),
        ];
    }
}

<?php
// Blocks/Hero/index.php

if (empty($heading)) return;
?>

<section class="hero">
    <h1><?php echo esc_html($heading); ?></h1>

    <?php if ($subtext): ?>
        <p><?php echo esc_html($subtext); ?></p>
    <?php endif; ?>

    <?php if ($image_url): ?>
        <img src="<?php echo esc_url($image_url); ?>" alt="">
    <?php endif; ?>
</section>

Step 3 — Render the block on a page

In TAW Theme, blocks aren't Gutenberg blocks: you queue and render them from your PHP templates.

<?php
// front-page.php

use TAW\Core\Block\BlockRegistry;

BlockRegistry::queue('hero');  // schedules CSS/JS for <head>
get_header();
?>

<?php BlockRegistry::render('hero'); ?>

<?php get_footer(); ?>

What you just built

• BlockLoader::loadAll() (called by Theme::boot()) discovered Blocks/Hero/Hero.php automatically — no registration required.
• Metabox rendered the admin UI and saved field values to post_meta.
• BlockRegistry::queue('hero') scheduled style.scss for <head> — only on pages that use this block.
• BlockRegistry::render('hero') called getData(), extracted the result, and loaded index.php.

Add a second block type: UI Block

UI Blocks are stateless components that receive props at render time — no metaboxes, no post_meta.

taw make:block Button --type=ui --with-style
composer dump-autoload

// Blocks/Button/Button.php
namespace TAW\Blocks\Button;

use TAW\Core\Block\Block;

class Button extends Block
{
    protected string $id = 'button';

    protected function defaults(): array
    {
        return [
            'text'  => '',
            'url'   => '#',
            'style' => 'primary',
        ];
    }
}

Use it inside any template or MetaBlock template:

<?php (new \TAW\Blocks\Button\Button())->render([
    'text' => 'Get Started',
    'url'  => '/contact',
]); ?>

Props are merged over the defaults() array — missing props always have safe fallbacks.

Multi-block pages

Queue multiple blocks at once, then render each where it belongs:

<?php
// front-page.php
use TAW\Core\Block\BlockRegistry;

BlockRegistry::queue('hero', 'features', 'stats', 'testimonials', 'cta');
get_header();
?>

<?php BlockRegistry::render('hero'); ?>
<?php BlockRegistry::render('features'); ?>
<?php BlockRegistry::render('stats'); ?>
<?php BlockRegistry::render('testimonials'); ?>
<?php BlockRegistry::render('cta'); ?>

<?php get_footer(); ?>

Production build

When you're ready to deploy:

npm run build

Vite outputs content-hashed CSS and JS to public/build/. WordPress loads these automatically when the dev server is not running.

Keep the site current

When taw/core releases a new version, update the theme in one step:

taw update

It works on a new branch, updates taw/core and the framework's files, runs the migrations and the checks, and opens a pull request. The theme's taw.json decides what it may change. See Updating a site.

Next steps