@wappi/engine

WordPress theme generation engine. Generate professional WordPress block themes programmatically with support for custom post types, typography, WooCommerce, styling systems, and more.

Features

• Block Theme Generation - Full WordPress FSE (Full Site Editing) block theme generation
• Custom Post Types - ACF-like meta fields with 25+ field types, repeaters, groups, and flexible content
• Custom Taxonomies - Hierarchical and non-hierarchical taxonomies with full WordPress options
• Advanced CPT Configuration - Fine-grained control over capability types, query vars, rewrite rules, and visibility
• Block Bindings - WordPress 6.5+ block bindings API support for connecting meta fields to block attributes
• Custom Blocks - Full Gutenberg block scaffolding with PHP rendering, block.json, CSS, and JavaScript
• CPT Block Templates - Auto-generated single and archive block templates for custom post types
• Spacing System - WordPress theme.json spacing scale with fluid clamp() values and layout configuration
• Typography System - Google Fonts integration with fluid typography, local font bundling, and font pairing recommendations
• WooCommerce Templates - Product pages, cart, checkout, My Account, and mini cart patterns
• Style Variations - Multiple color scheme presets (Blue, Green, Warm, Purple, Ocean)
• Styling System - SCSS, Tailwind CSS, Gulp build tools with 9 build features
• i18n Support - WordPress .pot file generation for translation-ready themes
• ZIP Packaging - Ready-to-install WordPress theme ZIP files
• ThemeForest Compliant - Generated code follows WordPress coding standards

Installation

npm install @wappi/engine

Quick Start

Generate a Block Theme

import { TemplateGenerator, ThemePackager } from '@wappi/engine';

const generator = new TemplateGenerator({
  name: 'My Theme',
  description: 'A custom WordPress theme',
  author: 'Your Name',
  version: '1.0.0',
  textDomain: 'my-theme',
  type: 'block',
});

// Generate individual files
const styleCss = generator.generateStyleCSS();
const themeJson = generator.generateThemeJSON();
const functionsPhp = generator.generateFunctionsPhp();
const indexHtml = generator.generateIndexTemplate();

// Package as ZIP
const files = [
  { path: 'style.css', content: styleCss },
  { path: 'theme.json', content: themeJson },
  { path: 'functions.php', content: functionsPhp },
  { path: 'templates/index.html', content: indexHtml },
];

const zipBuffer = await ThemePackager.createZip(files, 'my-theme');

Generate Custom Post Types

import { generateCPTFile } from '@wappi/engine';

const cpts = [{
  id: '1',
  name: 'Products',
  singularName: 'Product',
  slug: 'product',
  description: 'Custom products',
  public: true,
  hasArchive: true,
  showInMenu: true,
  showInRest: true,
  menuIcon: 'dashicons-products',
  supports: ['title', 'editor', 'thumbnail'],
  taxonomies: [],
  metaFields: [
    {
      id: '1',
      key: 'price',
      label: 'Price',
      type: 'number',
      required: true,
      min: 0,
      step: 0.01,
      prepend: '$',
    },
    {
      id: '2',
      key: 'gallery',
      label: 'Product Gallery',
      type: 'gallery',
      required: false,
      returnFormat: 'id',
      maxImages: 10,
    },
  ],
}];

const phpCode = generateCPTFile(cpts, 'my-theme', 'my_theme');

Typography Configuration

import { generateThemeJsonTypography, GOOGLE_FONTS } from '@wappi/engine';

const typography = generateThemeJsonTypography({
  primaryFont: { family: 'Inter', weights: [400, 500, 600], italicWeights: [400] },
  secondaryFont: { family: 'Playfair Display', weights: [500, 600, 700], italicWeights: [] },
  loadingStrategy: 'local',
  fluidTypography: true,
  fontSizes: {
    small: { min: '0.875rem', max: '0.875rem' },
    medium: { min: '1rem', max: '1.125rem' },
    large: { min: '1.25rem', max: '1.5rem' },
    xlarge: { min: '1.5rem', max: '2.5rem' },
  },
});

Spacing Configuration

import { generateSpacingSizes, DEFAULT_SPACING_CONFIG } from '@wappi/engine';

// Use defaults (WordPress standard scale with fluid spacing)
const spacingSizes = generateSpacingSizes(DEFAULT_SPACING_CONFIG);

// Or customize
const spacingSizes = generateSpacingSizes({
  spacingScale: [
    { slug: '10', name: 'XX-Small', size: '0.25rem' },
    { slug: '20', name: 'X-Small', size: '0.5rem' },
    { slug: '30', name: 'Small', size: '0.75rem' },
    { slug: '40', name: 'Medium', size: '1rem' },
    { slug: '50', name: 'Large', size: '1.5rem' },
  ],
  fluidSpacing: true,
  blockGap: '1.5rem',
  layout: { contentSize: '800px', wideSize: '1200px' },
});

Custom Taxonomies

import { generateTaxonomyRegistration } from '@wappi/engine';

const taxonomies = [{
  slug: 'genre',
  name: 'Genres',
  singularName: 'Genre',
  postTypes: ['book'],
  hierarchical: true,
  public: true,
  showInRest: true,
  rewriteSlug: 'genre',
}];

const phpCode = generateTaxonomyRegistration(taxonomies, 'my_theme');

Custom Blocks

import { generateCustomBlocksPhp, generateCustomBlockJson } from '@wappi/engine';

const blocks = [{
  slug: 'testimonial',
  title: 'Testimonial',
  description: 'Display a customer testimonial',
  category: 'widgets',
  postType: 'testimonial',
  fields: [
    { key: 'quote', label: 'Quote', type: 'textarea' },
    { key: 'author_name', label: 'Author', type: 'text' },
    { key: 'rating', label: 'Rating', type: 'number' },
  ],
}];

const phpCode = generateCustomBlocksPhp(blocks, 'my-theme', 'my_theme');
const blockJson = generateCustomBlockJson(blocks[0], 'my-theme');

Block Bindings (WordPress 6.5+)

import { generateBlockBindingsRegistration, getBindableFields } from '@wappi/engine';

const metaFields = [
  { key: 'price', label: 'Price', type: 'number' },
  { key: 'gallery', label: 'Gallery', type: 'gallery' },
];

const bindable = getBindableFields(metaFields); // filters to supported types
const phpCode = generateBlockBindingsRegistration(bindable, 'product', 'my-theme', 'my_theme');

API Reference

Generators

| Module | Description | |--------|-------------| | TemplateGenerator | Main Handlebars-based block theme file generator | | BlockThemeGenerator | Simplified block theme generator | | generateCPTFile() | Custom Post Type PHP code generator | | generateThemeJsonTypography() | WordPress theme.json typography settings | | generateSpacingSizes() | WordPress theme.json spacing scale (fluid/static) | | generatePotFile() | WordPress .pot translation file generator | | generateTaxonomyRegistration() | Custom taxonomy PHP code generator | | generateAdvancedCPTOverrides() | Advanced CPT registration arguments | | generateBlockBindingsRegistration() | WordPress 6.5+ block bindings API | | generateCPTSingleTemplate() | Single post block template for CPTs | | generateCPTArchiveTemplate() | Archive block template for CPTs | | generateCustomBlocksPhp() | Custom Gutenberg block PHP rendering | | generateCustomBlockJson() | block.json metadata for custom blocks | | generateCustomBlockStyle() | CSS for custom blocks | | generateCustomBlockScript() | JavaScript for custom blocks | | generateStylingFiles() | SCSS/Tailwind/Gulp build system generator |

Utilities

| Module | Description | |--------|-------------| | GOOGLE_FONTS | Curated list of 100+ premium Google Fonts | | getFontPairings() | Font pairing recommendations | | ThemePackager | ZIP file packaging with JSZip |

Types

All TypeScript types are fully exported for use in your application:

import type {
  ThemeConfig,
  GeneratedFile,
  TypographyConfig,
  CustomPostType,
  MetaField,
  // ... and many more
} from '@wappi/engine';

Configuration

Template Path

By default, Handlebars templates are loaded from the package's bundled templates/ directory. Override with:

process.env.WAPPI_TEMPLATES_PATH = '/path/to/custom/templates';

Font Path

For local font bundling, fonts are read from public/fonts/. Override with:

process.env.FONTS_PATH = '/path/to/fonts';

License

MIT