🌳 Bonsai CLI

A WordPress CLI tool for generating and managing reusable components, sections, and layouts in Roots-based WordPress projects.

Installation

Until beta release, install via Github w/ Composer (after that, it will be published to Packagist):

composer config repositories.bonsai-cli vcs git@github.com:jackalopelabs/bonsai-cli.git

Install via Composer:

composer require jackalopelabs/bonsai-cli:dev-main

Note: This package requires the Roots Stack (Sage, Bedrock, or Radicle) to be installed.

Features

⚡️ Quick setup with bonsai:init
🧱 Pre-built components library
📑 Template generation system
🎨 Section builder with dynamic data
📐 Layout management
🧹 Cleanup utilities

Commands

Initialize Project

Note: If you get

wp acorn bonsai:init

This sets up your project with:

Base component library
Example sections
Default layouts
Components page
Local configuration directory

If you get ERROR There are no commands defined in the "bonsai" namespace.

Run: wp @development acorn optimize:clear

Generate Site Template

wp acorn bonsai:generate [template]

Available templates:

cypress - Modern SaaS landing page
jackalope - Agency/portfolio site

Options:

--config=path/to/config.yml - Use custom config file

Create Components

wp acorn bonsai:component [name]

Available components:

accordion
card
cta
featured-grid
header
hero
list-item
pricing-box
widget

Create Sections

wp acorn bonsai:section [name] --component=[component] [--default]

Options:

--component - Specify component type
--default - Use default configuration without prompting

Create Layouts

wp acorn bonsai:layout [name] --sections=[section1,section2]

Cleanup

wp acorn bonsai:cleanup [--force]

Removes all generated:

Components
Sections
Layouts
Pages
Templates
Menu items

Project Structure

resources/views/
├── bonsai/
│   ├── components/
│   ├── sections/
│   └── layouts/
└── templates/

Detailed Examples

1. Building a Landing Page

# Initialize Bonsai
wp acorn bonsai:init

# Create sections using default content
wp acorn bonsai:section home_hero --component=hero --default
wp acorn bonsai:section features --component=card-featured --default
wp acorn bonsai:section faq --component=faq --default

# Create a layout combining the sections
wp acorn bonsai:layout landing --sections=home_hero,features,faq

# Generate the complete site
wp acorn bonsai:generate custom --config=config/bonsai/landing.yml

2. Custom Section Configuration

# config/bonsai/custom-hero.yml
sections:
  home_hero:
    component: hero
    data:
      title: "Welcome to Our Platform"
      subtitle: "The Future of Web Development"
      description: "Build better websites faster with our tools"
      imagePath: "images/hero-main.jpg"
      l1: "Easy to Use"
      l2: "Fully Customizable"
      l3: "Built for Speed"
      l4: "SEO Optimized"
      primaryText: "Get Started"
      primaryLink: "#signup"
      secondaryText: "Learn More"

3. Dynamic Component Generation

// Create a custom FAQ section
wp acorn bonsai:section product_faq --component=faq

// Example responses to prompts:
// Title: Product FAQ
// Number of FAQs: 3
// FAQ #1 Question: How do I install the product?
// FAQ #1 Answer: Installation is simple...

4. Advanced Layout Configuration

// Create a complex page layout
wp acorn bonsai:layout documentation --sections=doc_header,api_reference,code_examples,support_faq

// The layout will be generated at:
// resources/views/bonsai/layouts/documentation.blade.php

Troubleshooting

Common Issues

WSOD (White Screen of Death) After Generation

# First, check theme settings
wp option get template
wp option get stylesheet

# If incorrect, clean up and regenerate
wp acorn bonsai:cleanup --force
wp acorn bonsai:generate [template]

Missing Components

# Verify component installation
ls resources/views/bonsai/components

# Reinstall specific component
wp acorn bonsai:component [name]

Layout Not Finding Sections

# Check section paths
ls resources/views/bonsai/sections

# Regenerate sections if missing
wp acorn bonsai:section [name] --component=[type] --default

Asset Path Issues

# Verify public path in bud.config.ts
.setPublicPath(`/content/themes/[theme-name]/public/`)

Database Cleanup Issues

# Force cleanup and reset
wp acorn bonsai:cleanup --force
wp cache flush

Debug Steps

Component Generation
- Check component exists in package templates
- Verify component schema in SectionCommand
- Ensure proper permissions on directories
Section Building
- Validate section data format
- Check for missing dependencies
- Verify blade template syntax
Layout Issues
- Confirm section files exist
- Check section naming consistency
- Verify blade includes syntax

General Debug

# Enable WordPress debug mode
wp config set WP_DEBUG true --raw
wp config set WP_DEBUG_LOG true --raw

# Check logs
tail -f wp-content/debug.log

Configuration

Create custom site configurations in config/bonsai/:

name: My Site
description: Site description
version: 1.0.0

components:
  - hero
  - faq
  - slideshow

sections:
  home_hero:
    component: hero
    data:
      title: "Welcome"
      # ... component-specific data

layouts:
  main:
    sections:
      - home_hero
      - features

pages:
  home:
    title: "Home"
    layout: main

Best Practices

Always run bonsai:cleanup before regenerating a site
Use version control to track your configurations
Store sensitive data in .env rather than config files
Create reusable sections for common patterns

Compatibility

WordPress 6.0+
Roots Stack (Sage, Bedrock, or Radicle)
PHP 8.0+
Composer 2.0+

License

MIT License. See LICENSE for more information.

Bonsai Script

A wrapper script for running Bonsai CLI commands across different environments with automatic asset rebuilding.

Usage

From your project root:

./scripts/bonsai.sh <command> [--env=environment]

Environments

--env=development (default)
--env=staging
--env=production

You can also use the shorthand:

--development
--staging
--production

Examples

# Initialize Bonsai in development (default)
./scripts/bonsai.sh acorn bonsai:init

# Generate a site using the cypress template on staging
./scripts/bonsai.sh acorn bonsai:generate cypress --env=staging

# Clean up Bonsai files in production
./scripts/bonsai.sh acorn bonsai:cleanup --env=production

Asset Building

Development environment automatically rebuilds assets after Bonsai commands
Staging and production environments skip asset rebuilding
Asset rebuilding is only triggered for Bonsai-specific commands

Command Structure

./scripts/bonsai.sh [command] [--env=environment]

command:          The Bonsai command to execute (e.g., acorn bonsai:init)
--env:           Target environment (development|staging|production)

Features

Environment-specific command execution
Automatic asset rebuilding in development
Clear feedback and error messages
Defaults to development environment if none specified
Maintains proper exit codes from WP-CLI commands

Requirements

WP-CLI with configured environments (@development, @staging, @production)
Yarn for asset building (development only)
Proper SSH access to remote environments

Notes

Run the script from your project root directory
Make sure the script is executable (chmod +x scripts/bonsai.sh)
Asset rebuilding only occurs in development and only for Bonsai commands

Configuration Guide

Understanding YAML Templates

Bonsai uses YAML configuration files to define components, layouts, and pages. Here's a comprehensive guide on creating and modifying these templates.

Core Structure

Every Bonsai template requires these top-level keys:

name: "Your Project Name"
description: "Project description"
version: "0.0.1"
components: []
sections: {}
layouts: {}
pages: {}
wordpress: {}
assets: {}

Available Components

Bonsai includes these standard components:

hero
header
card
widget
pricing-box

Component Data Structures

Header Component

site_header:
  component: header
  data:
    siteName: string
    iconComponent: string # heroicon format
    navLinks: 
      - url: string
        label: string
    primaryLink: string
    containerClasses: string
    containerInnerClasses: string

Hero Component

home_hero:
  component: hero
  data:
    title: string
    subtitle: string
    description: string
    imagePaths: string # Single path, not array
    buttonText: string
    buttonLink: string
    secondaryText: string
    secondaryLink: string
    buttonLinkIcon: boolean
    secondaryIcon: boolean
    iconMappings:
      dropdownIcon: string
      buttonLinkIcon: string
      secondaryIcon: string

Card Component

services_card:
  component: card
  data:
    title: string
    subtitle: string
    features:
      - icon: string
        title: string
        description: string
    featureItems:
      - icon: string
        title: string
        description: string

Widget Component

features_widget:
  component: widget
  data:
    items:
      - id: string
        title: string
        icon: string
        content: string
        cta:
          title: string
          link: string
          imagePath: string # Single path, not array
        description: string
        listItems:
          - number: integer
            itemName: string
            text: string

Pricing Component

pricing:
  component: pricing
  data:
    title: string
    subtitle: string
    description: string
    pricingBoxes:
      - icon: string
        iconColor: string
        planType: string
        price: string
        features: string[]
        ctaLink: string
        ctaText: string
        ctaColor: string
        iconBtn: string
        iconBtnColor: string

Icon Usage

Bonsai uses Blade UI Kit's Heroicons implementation. Icons must be specified in one of these formats:

# Correct icon formats:
iconComponent: "heroicon-o-medical-bag"    # Outline style
iconComponent: "heroicon-m-medical-bag"    # Mini style
iconComponent: "heroicon-s-medical-bag"    # Solid style

# For icon mappings:
iconMappings:
  dropdownIcon: "heroicon-o-chevron-down"      # Outline
  buttonLinkIcon: "heroicon-o-arrow-right"     # Outline
  secondaryIcon: "heroicon-o-information-circle" # Outline

Common icon names:

arrow-right
chevron-down
information-circle
shopping-cart
user
cog
home
mail

Best practices:

Use outline (-o-) icons for most cases
Avoid mixing styles within the same component
Test icons in development before deploying
Check Heroicons.com for available icons
Use exact icon names from Heroicons (e.g., information-circle not info-circle)

Common Pitfalls

Image paths must be strings, not arrays
Component names must match exactly
All required fields must be present
Maintain proper YAML indentation
Use consistent data types
Use correct Heroicon format and names

Best Practices

Study working examples (bonsai.yml, cypress.yml)
Keep consistent formatting
Use descriptive names
Include all required sections
Test component compatibility
Maintain proper nesting levels

Testing Your Configuration

Compare against working templates
Verify all required fields
Check data type consistency
Validate component names
Ensure proper section references in layouts

Template Lookup Order

When running bonsai:generate [template], Bonsai looks for template files in this order:

/config/bonsai/templates/{template}.yml - Local project templates
/config/bonsai/{template}.yml - Legacy local config
/config/templates/{template}.yml - Legacy templates
Package default templates

This means you can:

Override any package template by creating a local version
Keep your custom templates separate from package defaults
Maintain your own template library in /config/bonsai/templates/
Fall back to package templates when no local version exists

Example:

# Use a local template
wp acorn bonsai:generate custom

# Use a package template
wp acorn bonsai:generate cypress

Files

README.md

Latest commit

History

README.md

File metadata and controls

🌳 Bonsai CLI

Installation

Features

Commands

Initialize Project

Generate Site Template

Create Components

Create Sections

Create Layouts

Cleanup

Project Structure

Detailed Examples

1. Building a Landing Page

2. Custom Section Configuration

3. Dynamic Component Generation

4. Advanced Layout Configuration

Troubleshooting

Common Issues

Debug Steps

Configuration

Best Practices

Compatibility

License

Bonsai Script

Usage

Environments

Examples

Asset Building

Command Structure

Features

Requirements

Notes

Configuration Guide

Understanding YAML Templates

Core Structure

Available Components

Component Data Structures

Header Component

Hero Component

Card Component

Widget Component

Pricing Component

Icon Usage

Common Pitfalls

Best Practices

Testing Your Configuration

Template Lookup Order