Getting started FAQ

Answers to the most common questions when setting up TAW Theme for the first time.

Installation

Do I need Gutenberg or the classic editor?

It depends on the theme. In TAW Theme, the classic theme this FAQ covers, blocks are plain PHP classes and templates, with no block editor registration and no block.json. The classic editor works fine, and so does Gutenberg (it just won't have TAW Theme's blocks in the inserter, which is intentional). TAW Gutenberg is the block theme, built for the Site Editor.

Do I need ACF or any other plugin?

No. TAW ships its own metabox engine (TAW\Core\Metabox\Metabox). Fields, validation, sanitization, and retrieval are all built in. No plugin dependencies for custom fields.

The composer create-project command fails. What's wrong?

TAW Theme is a private VCS package, so the --repository flag is required. Use this exact command:

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

Do I need to run composer install and npm install separately?

Yes. composer install pulls the PHP dependencies (including taw/core). npm install installs the frontend toolchain (Vite, Tailwind, Alpine.js). Both are required before you can run npm run dev.

Blocks

What's the difference between a MetaBlock and a UI Block?

	MetaBlock	UI Block
Data source	Metaboxes → `post_meta`	Props passed at render time
Admin UI	Metabox appears in page editor	None
Rendered via	`BlockRegistry::render('id')`	`(new Button())->render([...])`
Use case	Page sections (Hero, Stats, CTA)	Reusable components (Button, Card)

Why isn't my new block appearing?

Two common causes:

You forgot to run composer dump-autoload. This rebuilds Composer's PSR-4 classmap so PHP can find the new class.
The folder name does not match the class name. TAW's auto-discovery requires them to match exactly (e.g. Blocks/Hero/Hero.php with class Hero).

Can I have blocks inside subfolders?

Yes. Use --group= when scaffolding:

taw make:block Hero --group=sections   # → Blocks/sections/Hero/
taw make:block Badge --group=ui/cards  # → Blocks/ui/cards/Badge/

BlockLoader::loadAll() scans recursively to any depth.

Can I use a block on a post type other than page?

Yes. Set the screen option in your Metabox config:

new Metabox([
    'screen' => 'post', // or any registered post type slug
    ...
]);

Assets

Why aren't my block styles loading?

Make sure you called BlockRegistry::queue('block-id') before get_header() in your template. This schedules the block's assets for <head>. If you call only render() without queuing first, assets are enqueued as a fallback but land after <head> closes.

Can a block have both CSS and JS?

Yes. Place style.scss (or style.css) and script.js in the block folder. Both are auto-detected. SCSS takes priority over CSS when both exist. JS is loaded in the footer as type="module".

How do I reference a font or other asset from a template?

Use the global vite_asset_url() helper:

$fontUrl = vite_asset_url('resources/fonts/Inter-Regular.woff2');

This returns the correct URL whether the Vite dev server is running or not.

Updates

How do I update the framework?

On taw/core 1.91 or later:

taw update

It updates taw/core and the framework's files on a new branch, runs the checks, and opens a pull request, without touching your blocks or templates. On an older taw/core, run composer update taw/core --with-dependencies. See Updating a site and Upgrading taw/core.

Does TAW have auto-updates in WordPress admin?

Not by default. taw/core has a TAW\Core\Theme\ThemeUpdater that shows WordPress's Update Available notice from a theme's GitHub Releases, but TAW Theme doesn't turn it on (see Theme updates). Updates normally go through Composer and taw update, so the theme's code changes in git, with a pull request.

Was this page helpful?