Custom WordPress Themes: A Practical Modern Workflow

Building a custom WordPress theme in a maintainable way means using a clear structure, modern asset tooling, and patterns that play well with blocks and the editor.

Theme structure

Keep the theme lean: style.css and functions.php for metadata and bootstrapping; separate PHP templates for each template type (e.g. index.php, single.php, page.php, front-page.php). Use template parts (e.g. get_template_part('parts/header')) so header, footer, and repeated blocks live in one place. Put assets (JS, CSS) in a subfolder and build them with a bundler (e.g. Vite, webpack) so you get hashed filenames and tree-shaking; enqueue the built files in functions.php with wp_enqueue_script and wp_enqueue_style. That keeps the theme directory clear and makes updates predictable.

Block-based vs classic

WordPress is block-based by default. You can still use classic templates and the block editor will wrap content in blocks. For full control, build block templates in HTML in your PHP files or use the Site Editor (FSE) if the project is block-only. For a classic custom theme, design your templates in PHP and use the_content() so editors can use blocks inside the content area. Register any custom blocks you need (e.g. ACF blocks or custom block.json blocks) and keep block assets in the build pipeline.

Local and deployment

Develop locally with something like Local by Flywheel, Docker, or a LAMP stack. Use a single wp-config pattern (env vars for DB and URLs) so the same codebase works in dev and production. Deploy the theme (and only the theme) via Git: build assets, commit the built files or build on the server, and pull on the server. Avoid editing theme files in production; use version control and a clear deploy step so you can roll back.

// functions.php - enqueue built assets
function my_theme_assets() {
  $ver = filemtime(get_template_directory() . '/dist/main.css');
  wp_enqueue_style('my-theme', get_template_directory_uri() . '/dist/main.css', [], $ver);
  wp_enqueue_script('my-theme', get_template_directory_uri() . '/dist/main.js', [], $ver, true);
}
add_action('wp_enqueue_scripts', 'my_theme_assets');

Summary

Use a clear theme structure, template parts, and a build step for assets. Support the block editor where it makes sense and register custom blocks if needed. Develop locally with env-based config and deploy the theme via Git with built assets. That’s a practical modern workflow for custom WordPress themes.