Skip to content

giuseppe-trisciuoglio/developer-kit / plugins/developer-kit-php/skills/wordpress/wordpress-sage-theme

wordpress-sage-theme

Verified

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.

FileKindSize
SKILL.mdskill md12.6 KB
assets/starter-layout.blade.phpscript549 B
assets/starter-page.blade.phpscript1.6 KB
references/acf.mdmarkdown9.5 KB
references/blade.mdmarkdown5.1 KB
references/bud.mdmarkdown5.0 KB
references/sage.mdmarkdown2.4 KB

references/bud.md

View on GitHub
# Bud Build Configuration Reference

Complete reference for configuring Bud (Sage's build tool based on Vite).

## Configuration File

**bud.config.js** - Main configuration file in theme root.

## Basic Configuration

```js
import config from '@roots/bud'

export default async (app) => {
  app
    .entry({
      app: ['./resources/scripts/main.js', './resources/styles/main.scss'],
      editor: ['./resources/scripts/editor.js', './resources/styles/editor.scss'],
    })
    .publicPath('/wp-content/themes/my-theme/public/')
}
```

## Entry Points

Define multiple entry points for different contexts:

```js
app.entry({
  // Frontend
  app: ['@scripts/main', '@styles/main'],

  // Editor (Gutenberg)
  editor: ['@scripts/editor', '@styles/editor'],

  // Custom admin
  admin: ['@scripts/admin', '@styles/admin'],
})
```

## Asset Management

### Copy Assets

```js
app.assets('images', 'fonts')
```

Copy files from `resources/` to `public/`:

```
resources/images/logo.png → public/images/logo.png
resources/fonts/inter.woff2 → public/fonts/inter.woff2
```

### Custom Paths

```js
app.assets(['images', 'fonts', 'icons'])
```

## Runtime

Enable runtime manifest for dynamic asset loading:

```js
app.runtime()
```

Creates `public/manifest.json` with asset mappings.

## Tailwind CSS

### Enable Tailwind

```js
import tailwindcss from '@roots/bud-tailwindcss'

app.use(tailwindcss)
```

### Configuration

**tailwind.config.js**:

```js
export default {
  content: [
    './resources/views/**/*.blade.php',
    './resources/scripts/**/*.js',
  ],
  theme: {
    extend: {
      colors: {
        primary: '#1e40af',
        secondary: '#7c3aed',
      },
    },
  },
}
```

## Sass Configuration

### Options

```js
app.tailwind({
  options: {
    includePaths: ['node_modules'],
  },
})
```

## Aliases

Create import aliases:

```js
app.alias({
  '@': 'resources',
  '@scripts': 'resources/scripts',
  '@styles': 'resources/styles',
  '@components': 'resources/views/components',
})
```

Usage in JavaScript:

```js
import Button from '@/components/button'
```

## Minification

Control minification per environment:

```js
app.minimize(true) // Always minimize
app.minimize(false) // Never minimize
app.minimize(!app.isDevelopment) // Only in production
```

## Source Maps

```js
app.js({ sourcemaps: true })
```

## Dev Server

### Proxy Configuration

```js
app.proxy('http://localhost:3000')
```

### Watch Paths

```js
app.watch([
  'resources/views/**/*.blade.php',
  'app/**/*.php',
])
```

### Server Options

```js
app.server({
  host: 'localhost',
  port: 3000,
  hmr: true,
})
```

## PostCSS

### Plugins

```js
import postcssPresetEnv from 'postcss-preset-env'

app.postcss.set('plugins', [
  postcssPresetEnv({ stage: 1 }),
])
```

## Dependencies

### External Dependencies

```js
app.provide({
  $: 'jquery',
  jQuery: 'jquery',
  'window.jQuery': 'jquery',
})
```

### Vendor Splitting

```js
app.vendor('jquery', 'lodash')
```

## Optimization

### Split Chunks

```js
app.splitChunks(false) // Disable
app.splitChunks({
  strategy: 'default', // or 'single', 'all'
})
```

### Lazy Loading

```js
app.optimization.moduleChunks(true)
```

## Environment

### Detection

```js
app.isDevelopment // true in dev mode
app.isProduction  // true in production
```

### Conditional Config

```js
if (app.isProduction) {
  app.minimize()
}

if (app.isDevelopment) {
  app.devtool('eval-cheap-module-source-map')
}
```

## Commands Reference

```bash
# Development
npm run dev           # Start dev server with HMR
npm run dev -- --watch  # Watch mode without server

# Production
npm run build         # Build for production
npm run build -- --minify  # Build with extra minification

# Utilities
npm run clean         # Clean build directory
npm run check         # Check configuration
```

## Complete Example

```js
import config from '@roots/bud'
import tailwindcss from '@roots/bud-tailwindcss'

export default async (app) => {
  app
    // Entry points
    .entry({
      app: ['@scripts/main', '@styles/main'],
      editor: ['@scripts/editor', '@styles/editor'],
    })
    // Public path
    .publicPath('/wp-content/themes/my-theme/public')
    // Runtime manifest
    .runtime()
    // Asset copying
    .assets('images', 'fonts')
    // Tailwind
    .use(tailwindcss)
    // Aliases
    .alias({
      '@': 'resources',
      '@scripts': 'resources/scripts',
      '@styles': 'resources/styles',
    })
    // Minification
    .minimize(!app.isDevelopment)
    // Source maps
    .js({ sourcemaps: app.isDevelopment })
    // Dev server
    .proxy('http://localhost:3000')
    .watch([
      'resources/views/**/*.blade.php',
      'app/**/*.php',
    ])
}
```

## Troubleshooting

### HMR Not Working

Check proxy URL matches WordPress URL:

```js
app.proxy('http://localhost:3000') // Must match WP_URL
```

### Assets 404

Ensure public path is correct:

```js
app.publicPath('/wp-content/themes/my-theme/public/')
```

### Tailwind Classes Not Generated

Check content paths in `tailwind.config.js`:

```js
content: [
  './resources/views/**/*.blade.php', // Include Blade files
]
```
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall