Docs – bonsai.so

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

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

1. 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]

2. Missing Components

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

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

3. Layout Not Finding Sections

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

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

4. Asset Path Issues

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

5. 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

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