/wordpress-sage-theme

name: wordpress-sage-theme
description: 'Provides WordPress theme development patterns using Sage (roots/sage) framework. Use when creating, modifying, or debugging WordPress themes with Sage, including (1): creating new Sage themes from scratch, (2): setting up Blade templates and components, (3): configuring build tools (Vite, Bud), (4): working with WordPress theme templates and hierarchy, (5): implementing ACF fields integration, (6): theme customization and asset management.'
allowed-tools: Read, Write, Bash, Glob, Grep

WordPress Sage Theme Development

Overview

Sage is a WordPress theme framework by Roots that provides modern development practices including Blade templates, dependency management with Composer, and build tools with Vite/Bud.

When to Use

• Creating new Sage themes from scratch or from composer templates
• Setting up Blade templates, layouts, and reusable components
• Configuring build tools (Bud/Vite) for asset compilation
• Working with WordPress template hierarchy in Blade format
• Integrating Advanced Custom Fields (ACF) with Blade templates
• Debugging theme rendering, asset loading, or build issues

Instructions

1. **Set up the environment**: Install PHP 8.0+, Node.js 18+, Composer, and create a new Sage theme with `composer create-project roots/sage` 2. **Configure build tools**: Run `npm install && composer install`, then configure `bud.config.js` for asset entries and Tailwind 3. **Create Blade templates**: Place templates in `resources/views/`, using layouts in `layouts/`, components in `components/` 4. **Wire up WordPress templates**: Map WordPress template hierarchy to Blade files (e.g., `page.blade.php` for page templates) 5. **Integrate ACF fields**: Use `get_field()` for basic fields, `have_rows()` loops for repeaters and flexible content 6. **Build and verify**: Run `npm run build`, verify `public/manifest.json` exists, check browser console for asset errors 7. **Deploy**: Ensure the production build step (`npm run build`) runs during deployment; raw source files cannot be served directly

Examples

**Create a new Sage theme:**

composer create-project roots/sage my-theme
cd my-theme
npm install && composer install
npm run dev

**Blade page template:**

@extends('layouts.app')

@section('content')
  <main class="content">
    <h1>{{ the_title() }}</h1>
    <div class="entry-content">
      {{ the_content() }}
    </div>
  </main>
@endsection

**ACF flexible content in Blade:**

@if (have_rows('flexible_content'))
  @while (have_rows('flexible_content'))
    @php the_row() @endphp
    @switch(get_row_layout())
      @case('hero_section')
        @include('components.hero')
        @break
    @endswitch
  @endwhile
@endif

Quick Start

Creating a New Sage Theme

**Prerequisites**: PHP 8.0+, Node.js 18+, Composer

# Create new Sage theme
wp scaffold theme-theme my-theme --theme_name="My Theme" --author="Your Name" --activate

# Or install Sage directly via Composer
composer create-project roots/sage my-theme
cd my-theme

# Install dependencies
npm install
composer install

# Build for development
npm run dev

# Build for production
npm run build

Directory Structure

resources/
├── views/           # Blade templates
│   ├── layouts/     # Base layouts (app.blade.php)
│   ├── components/  # Reusable components
│   └── partials/    # Template partials
├── styles/          # CSS/SASS files
│   └── main.scss    # Main stylesheet
└── scripts/         # JavaScript files
    └── main.js      # Main JavaScript

Blade Templates

Layouts

**Base Layout** (`resources/views/layouts/app.blade.php`):

<!DOCTYPE html>
<html {{ site_html_language_attributes() }}>
  <head>
    {{ wp_head() }}
  </head>
  <body {{ body_class() }}>
    @yield('content')
    {{ wp_footer() }}
  </body>
</html>

Template Hierarchy Mapping

| WordPress Template | Sage Blade File | |-------------------|-----------------| | front-page.php | `views/front-page.blade.php` | | single.php | `views/single.blade.php` | | page.php | `views/page.blade.php` | | archive.php | `views/archive.blade.php` | | index.php | `views/index.blade.php` |

**Example Page Template** (`resources/views/page.blade.php`):

@extends('layouts.app')

@section('content')
  <main class="content">
    <h1>{{ the_title() }}</h1>
    <div class="entry-content">
      {{ the_content() }}
    </div>
  </main>
@endsection

Components

**Reusable Button Component** (`resources/views/components/button.blade.php`):

@props(['url' => '#', 'text' => 'Click', 'variant' => 'primary'])

<a href="{{ $url }}" class="btn btn-{{ $variant }}">
  {{ $text }}
</a>

**Usage**:

<x-button url="/contact" text="Contact Us" variant="secondary" />

ACF Integration

Displaying ACF Fields

**Basic Field**:

@while(the_post())
  <h1>{{ get_field('hero_title') ?? the_title() }}</h1>
  <p>{{ get_field('hero_description') }}</p>
@endwhile

**Flexible Content**:

@if (have_rows('flexible_content'))
  @while (have_rows('flexible_content'))
    @php the_row() @endphp

    @switch(get_row_layout())
      @case('hero_section')
        @include('components.hero')
        @break

      @case('features_grid')
        @include('components.features-grid')
        @break
    @endswitch
  @endwhile
@endif

**Repeater Field**:

@if (have_rows('testimonials'))
  <div class="testimonials">
    @while (have_rows('testimonials'))
      @php the_row() @endphp
      <blockquote>
        <p>{{ get_sub_field('testimonial_text') }}</p>
        <cite>{{ get_sub_field('author_name') }}</cite>
      </blockquote>
    @endwhile
  </div>
@endif

Build Configuration (Bud)

Tailwind CSS Setup

**Install Tailwind**:

npm install -D tailwindcss
npx tailwindcss init -p

**Configure** (`bud.config.js`):

export default async (app) => {
  app
    .entry({
      app: [