Custom WordPress Theme Development from Scratch

WordPress Custom Theme Development From Scratch

Custom theme — only right path when design doesn't fit framework bounds, maximum performance needed without third-party framework ballast, or site must precisely match brand style. Development via PHP + modern CSS + vanilla JS or bundler.

Theme Structure

my-theme/
├── style.css              # Theme header (mandatory)
├── functions.php          # Hooks, resource registration
├── index.php              # Fallback template
├── header.php
├── footer.php
├── single.php             # Post template
├── page.php               # Page template
├── archive.php
├── search.php
├── 404.php
├── front-page.php         # Homepage
├── template-parts/
│   ├── content-post.php
│   ├── content-card.php
│   └── navigation.php
├── inc/
│   ├── theme-setup.php
│   ├── enqueue.php
│   ├── custom-post-types.php
│   └── acf-fields.php
├── src/
│   ├── scss/
│   └── js/
└── package.json

functions.php: Proper Structure

<?php
// Load modularly, don't write everything in one file
require get_template_directory() . '/inc/theme-setup.php';
require get_template_directory() . '/inc/enqueue.php';
require get_template_directory() . '/inc/custom-post-types.php';

inc/theme-setup.php:

<?php
function mytheme_setup(): void {
    add_theme_support('title-tag');
    add_theme_support('post-thumbnails');
    add_theme_support('html5', ['search-form', 'comment-form', 'gallery', 'caption', 'style', 'script']);
    add_theme_support('custom-logo', [
        'height' => 60,
        'width' => 200,
        'flex-height' => true,
    ]);
    add_theme_support('woocommerce'); // if needed

    load_theme_textdomain('mytheme', get_template_directory() . '/languages');

    register_nav_menus([
        'primary' => __('Primary Menu', 'mytheme'),
        'footer'  => __('Footer Menu', 'mytheme'),
    ]);
}
add_action('after_setup_theme', 'mytheme_setup');

Asset Enqueuing

function mytheme_enqueue_assets(): void {
    $theme_version = wp_get_theme()->get('Version');

    // CSS
    wp_enqueue_style(
        'mytheme-style',
        get_template_directory_uri() . '/dist/css/main.css',
        [],
        $theme_version
    );

    // JS (defer for performance)
    wp_enqueue_script(
        'mytheme-main',
        get_template_directory_uri() . '/dist/js/main.js',
        [],
        $theme_version,
        ['strategy' => 'defer', 'in_footer' => true]
    );

    // Pass data to JS
    wp_localize_script('mytheme-main', 'siteData', [
        'ajaxUrl' => admin_url('admin-ajax.php'),
        'nonce'   => wp_create_nonce('mytheme_nonce'),
        'homeUrl' => home_url(),
    ]);
}
add_action('wp_enqueue_scripts', 'mytheme_enqueue_assets');

Post Template (single.php)

<?php get_header(); ?>

<main id="main" class="site-main">
    <?php
    while (have_posts()) :
        the_post(); ?>

        <article id="post-<?php the_ID(); ?>" <?php post_class('entry'); ?>>
            <header class="entry-header">
                <?php if (has_post_thumbnail()) : ?>
                    <div class="entry-thumbnail">
                        <?php the_post_thumbnail('large', ['loading' => 'eager', 'fetchpriority' => 'high']); ?>
                    </div>
                <?php endif; ?>

                <h1 class="entry-title"><?php the_title(); ?></h1>

                <div class="entry-meta">
                    <time datetime="<?php echo get_the_date('c'); ?>">
                        <?php echo get_the_date(); ?>
                    </time>
                </div>
            </header>

            <div class="entry-content">
                <?php the_content(); ?>
            </div>
        </article>

    <?php endwhile; ?>
</main>

<?php get_sidebar(); ?>
<?php get_footer(); ?>

Build with Vite

// vite.config.js
import { defineConfig } from 'vite';
import liveReload from 'vite-plugin-live-reload';

export default defineConfig({
  plugins: [liveReload('**/*.php')],
  build: {
    outDir: 'dist',
    rollupOptions: {
      input: {
        main: 'src/js/main.js',
        admin: 'src/js/admin.js',
      },
    },
  },
  css: {
    preprocessorOptions: {
      scss: { additionalData: '@use "src/scss/variables" as *;' },
    },
  },
});

Timeline

Basic theme with templates (homepage, blog, page, 404) without design — 2–3 days. Theme per finished design with 10–15 page types, ACF fields and custom post types — 2–3 weeks.