@10up/block-renderer-patterns

Scan WordPress theme pattern directories and parse PHP file headers to extract pattern metadata and content.

Installation

npm install @10up/block-renderer-patterns
# or
pnpm add @10up/block-renderer-patterns

Overview

WordPress themes can define block patterns in PHP files within the /patterns directory. This package:

1. Scans pattern directories - Both /patterns and /synced-patterns
2. Parses PHP headers - Extracts metadata from PHP file docblocks
3. Extracts block content - Gets the actual block markup
4. Creates a searchable registry - Query patterns by category, block type, or keywords

Usage

Load All Patterns from Theme

The main entry point - loads all patterns and returns a registry:

import { loadPatterns } from '@10up/block-renderer-patterns';

const registry = loadPatterns('/path/to/theme');

// Iterate over all patterns
for (const [slug, pattern] of registry) {
  console.log(pattern.slug);        // 'theme-name/hero-section'
  console.log(pattern.title);       // 'Hero Section'
  console.log(pattern.categories);  // ['featured', 'banner']
  console.log(pattern.content);     // '<!-- wp:group -->...'
}

// Get a specific pattern
const heroPattern = registry.get('theme-name/hero-section');

Scan Patterns with Error Reporting

Get detailed scan results including errors:

import { scanPatterns, createPatternRegistry } from '@10up/block-renderer-patterns';

const result = scanPatterns('/path/to/theme');

// Check for errors
if (result.errors.length > 0) {
  console.log('Failed to parse:');
  for (const error of result.errors) {
    console.log(`  ${error.filePath}: ${error.error}`);
  }
}

// Access successfully parsed patterns
console.log(`Found ${result.patterns.length} patterns`);

// Create a registry from results
const registry = createPatternRegistry(result);

Parse Single Pattern File

import { parsePatternFile } from '@10up/block-renderer-patterns';

const pattern = parsePatternFile(
  '/path/to/theme/patterns/hero.php',
  'theme-name',  // Theme name for slug prefix
  false          // isSynced flag
);

console.log(pattern);
// {
//   slug: 'theme-name/hero',
//   title: 'Hero Section',
//   description: 'A hero section with...',
//   categories: ['featured'],
//   keywords: ['hero', 'banner'],
//   blockTypes: ['core/post-content'],
//   inserter: true,
//   content: '<!-- wp:group -->...',
//   filePath: '/path/to/theme/patterns/hero.php',
//   isSynced: false
// }

Parse PHP Header Only

Extract metadata from a PHP file's docblock:

import { parsePatternHeader } from '@10up/block-renderer-patterns';

const phpContent = `<?php
/**
 * Title: Hero Section
 * Slug: theme-name/hero
 * Categories: featured, banner
 * Keywords: hero, cta
 * Block Types: core/post-content
 * Viewport Width: 1200
 */
?>
<!-- wp:group -->...`;

const metadata = parsePatternHeader(phpContent);
// {
//   title: 'Hero Section',
//   slug: 'theme-name/hero',
//   categories: ['featured', 'banner'],
//   keywords: ['hero', 'cta'],
//   blockTypes: ['core/post-content'],
//   viewportWidth: 1200
// }

Extract Block Content

Get the block markup without the PHP header:

import { extractPatternContent } from '@10up/block-renderer-patterns';

const content = extractPatternContent(phpContent);
// '<!-- wp:group -->...'

Querying Patterns

Get Patterns by Category

import { loadPatterns, getPatternsByCategory } from '@10up/block-renderer-patterns';

const registry = loadPatterns('/path/to/theme');
const featuredPatterns = getPatternsByCategory(registry, 'featured');
// Returns PatternDefinition[]

Get Patterns by Block Type

Patterns can be associated with specific block types:

import { getPatternsByBlockType } from '@10up/block-renderer-patterns';

// Get patterns for the post content block
const contentPatterns = getPatternsByBlockType(registry, 'core/post-content');

Search Patterns

Search across title, description, keywords, and slug:

import { searchPatterns } from '@10up/block-renderer-patterns';

const results = searchPatterns(registry, 'hero');
// Returns patterns matching "hero" in any searchable field

Get All Categories

import { getAllCategories } from '@10up/block-renderer-patterns';

const categories = getAllCategories(registry);
// ['banner', 'featured', 'footer', 'header', ...]

Types

PatternDefinition

interface PatternDefinition {
  /** Human-readable title */
  title: string;
  /** Pattern slug, e.g., "theme-name/hero" */
  slug: string;
  /** Pattern categories */
  categories?: string[];
  /** Search keywords */
  keywords?: string[];
  /** Pattern description (for screen readers) */
  description?: string;
  /** Block types this pattern applies to */
  blockTypes?: string[];
  /** Post types where this pattern can be used */
  postTypes?: string[];
  /** Preview iframe width */
  viewportWidth?: number;
  /** Whether to show in inserter (default true) */
  inserter?: boolean;
  /** The actual block markup content */
  content: string;
  /** Source file path */
  filePath: string;
  /** Whether this is a synced pattern (reusable block) */
  isSynced: boolean;
}

PatternRegistry

type PatternRegistry = Map<string, PatternDefinition>;

PatternScanResult

interface PatternScanResult {
  /** Successfully parsed patterns */
  patterns: PatternDefinition[];
  /** Files that failed to parse */
  errors: Array<{
    filePath: string;
    error: string;
  }>;
}

PatternMetadata

interface PatternMetadata {
  title?: string;
  slug?: string;
  categories?: string[];
  keywords?: string[];
  description?: string;
  blockTypes?: string[];
  postTypes?: string[];
  viewportWidth?: number;
  inserter?: boolean;
}

Complete Exports

Functions

| Function | Description | |----------|-------------| | loadPatterns(themePath) | Load all patterns and return a registry | | scanPatterns(themePath) | Scan patterns with error reporting | | createPatternRegistry(scanResult) | Create registry from scan results | | parsePatternFile(filePath, themeName, isSynced) | Parse single pattern file | | parsePatternHeader(content) | Parse PHP header to metadata | | extractPhpCommentHeader(content) | Extract raw PHP docblock | | extractPatternContent(content) | Extract block markup from PHP | | getPatternsByCategory(registry, category) | Filter patterns by category | | getPatternsByBlockType(registry, blockType) | Filter patterns by block type | | searchPatterns(registry, query) | Search patterns by keyword | | getAllCategories(registry) | Get all unique categories |

Types

| Type | Description | |------|-------------| | PatternDefinition | Complete pattern with metadata and content | | PatternRegistry | Map of slug to pattern definition | | PatternScanResult | Scan results with patterns and errors | | PatternMetadata | Metadata extracted from PHP header |

Zod Schemas

| Schema | Description | |--------|-------------| | patternMetadataSchema | Validate pattern metadata objects | | patternDefinitionSchema | Validate complete pattern definitions |

License

MIT