Block Rendering Issues

Symptoms

• Commerce blocks not appearing in editor
• Blocks render as empty on frontend
• “This block contains unexpected or invalid content” error
• Block styling broken or missing
• Product data not loading in blocks

Common Causes

1. Parent Block Requirements

• Child blocks placed without required parent
• Incorrect block nesting hierarchy
• Parent block context not available

2. Missing BigCommerce Data

• Product not synced to WordPress®
• Product variant/option data incomplete
• GraphQL query returning empty results

3. Build/Asset Issues

• Block JavaScript not loading
• CSS files missing or not enqueued
• Commons chunk dependency missing
• block.json file not found

4. Theme Compatibility

• Theme blocking editor styles
• CSS conflicts with theme styles
• Theme not loading block assets
• Font family or color variables not available

Solutions

Fix Parent-Child Block Errors

Some blocks require specific parent blocks to function:

Example: Product variants must be inside Product Details

❌ Wrong:

- Product Variants block (standalone)

✅ Correct:

- Product Details block
  - Product Variants block (child)

To fix in editor:

1. Remove the standalone child block
2. Add the parent block (e.g., Product Details)
3. The child block should auto-populate inside parent
4. If not, manually add the child block inside parent

Verify Product Data Sync

If blocks render but show no products:

1. Check product sync status:

   wp post list --post_type=bigcommerce_product --posts_per_page=5

2. Verify products exist in WordPress® database

3. Force resync if products missing:

   • Go to Commerce Connect → Settings → Advanced
   • Click “Sync Products Now”

4. Check specific product has required data:

   wp post get 123 --format=json

Fix Missing Block Assets

If blocks don’t appear in editor or show as broken:

1. Verify build directory exists:

   ls -la wp-content/plugins/commerce-connect/build/

2. Check for block.json files:

   find wp-content/plugins/commerce-connect/build/ -name "block.json"

3. Rebuild assets if missing:

   cd wp-content/plugins/commerce-connect
   npm install
   npm run build

4. Clear WordPress® cache:

   wp cache flush

Fix Commons Chunk Dependency

All blocks depend on the commerce-connect-commons.js shared chunk:

1. Verify commons script registered:

   wp eval 'wp_scripts(); print_r(wp_scripts()->registered["commerce-connect-commons"]);'

2. Check commons asset file exists:

   ls -la wp-content/plugins/commerce-connect/build/commerce-connect-commons.asset.php

3. If missing, rebuild:

   npm run build

Fix Theme Style Conflicts

If blocks display but styling is broken:

1. Check editor styles loaded:

   • Open block editor
   • Inspect element with DevTools
   • Look for ecom-ui-styles.css in Network tab

2. Verify CSS variables available:

   // In browser console
   getComputedStyle(document.documentElement).getPropertyValue('--ecom-ui-primary-button-color-background');

3. If empty, check theme.json has color/typography settings:

   {
     "settings": {
       "color": {
         "palette": [...]
       },
       "typography": {
         "fontFamilies": [...]
       }
     }
   }

4. Regenerate CSS variables:

   • Go to Commerce Connect → Settings → Design
   • Click “Reset to Theme Defaults”
   • Save settings to regenerate inline styles

Fix Block Category Not Showing

If Commerce Connect blocks don’t appear in editor:

1. Verify block category registered:

   wp eval '
   $categories = get_default_block_categories();
   foreach($categories as $cat) {
     if($cat["slug"] === "commerce-connect") {
       print_r($cat);
     }
   }'

2. Check for JavaScript errors in browser console

3. Try refreshing editor or clearing browser cache

Debug Block Render Issues

For blocks that render empty or show errors:

1. Enable WordPress® debug mode:

   wp-config.php

   define('WP_DEBUG', true);
   define('WP_DEBUG_LOG', true);
   define('SCRIPT_DEBUG', true);

2. Check browser console for JavaScript errors

3. Inspect block attributes:

   • Click block in editor
   • Open DevTools → Console
   • Type: wp.data.select('core/block-editor').getSelectedBlock()
   • Verify attributes are populated correctly

Verification

After applying fixes:

1. Refresh block editor (Ctrl+Shift+R / Cmd+Shift+R)
2. Add Commerce Connect block to page
3. Verify block appears in editor with preview
4. Configure block settings (product selection, layout, etc.)
5. Preview/publish page to check frontend rendering
6. Inspect frontend HTML for block markup

Success indicators:

• Block appears in editor block inserter
• Block preview shows in editor (not empty box)
• Block settings panel shows configuration options
• Frontend shows product data with correct styling
• No JavaScript errors in browser console
• CSS styles applied correctly

Prevention

Maintain Build Process

1. Run npm run build after plugin updates
2. Commit build/ directory to version control
3. Verify assets exist before deploying to production
4. Use npm ci instead of npm install for consistent builds

Test Block Compatibility

1. Test blocks with active theme before going live
2. Check editor and frontend rendering
3. Test responsive layouts on mobile/tablet
4. Verify accessibility (keyboard nav, screen readers)

Monitor Asset Loading

1. Enable query monitor plugin (optional) to track enqueued scripts
2. Check Network tab for 404 errors on block assets
3. Verify CDN/caching not blocking block assets
4. Test with caching disabled if layout issues occur

Document Block Requirements

For client/team documentation:

1. List parent-child block relationships clearly
2. Note any theme requirements (theme.json support, etc.)
3. Document required plugins (none currently, but may change)
4. Provide block usage examples with screenshots

Advanced Debugging

Inspect Block Registration

Check which blocks are registered:

wp eval '
$registry = WP_Block_Type_Registry::get_instance();
$blocks = $registry->get_all_registered();
foreach($blocks as $name => $block) {
  if(strpos($name, "commerce-connect") !== false) {
    echo "$name\n";
  }
}'

Check Block Dependencies

Verify block script dependencies:

wp eval '
$block_type = WP_Block_Type_Registry::get_instance()
  ->get_registered("commerce-connect/product-grid");
print_r($block_type->editor_script_handles);
print_r($block_type->view_script_handles);
'

Should include commerce-connect-commons in dependencies.

Block Discovery Process

Understanding how blocks are found:

1. Plugin scans build/ directory recursively
2. Looks for block.json files at any depth
3. Registers each block found via register_block_type()
4. Adds dependencies: Editor styles + commons chunk
5. Creates category “Commerce Connect” for grouping

If blocks not appearing:

• Check build/ directory has proper structure
• Verify block.json exists and is valid JSON
• Look for PHP errors during plugin activation
• Check plugin is active and not in “must-use plugins”

CSS Variable Mapping

Block styles depend on theme CSS variables:

/* Generated from theme.json */
:root {
  --ecom-ui-primary-button-color-background: var(--wp--preset--color--primary);
  --ecom-ui-primary-button-color-text: var(--wp--preset--color--contrast);
  --ecom-ui-heading-h1-font-family: var(--wp--preset--font-family--heading);
  /* ... */
}

If variables missing:

• Theme doesn’t use theme.json - Blocks will use fallback defaults
• Theme.json missing settings - Specific styles won’t map
• Solution: Add missing settings to theme.json or use plugin settings override

Common Block.json Issues

Invalid block.json causes registration to fail:

{
  "apiVersion": 2,
  "name": "commerce-connect/product-grid",
  "title": "Product Grid",
  "category": "commerce-connect",
  "editorScript": "file:./index.js",
  "style": "file:./style-index.css"
}

Required fields:

• apiVersion - Must be 2 or 3
• name - Must be unique and namespaced
• title - Display name in editor
• category - Must exist (commerce-connect is registered by plugin)

Verify with:

cat build/product-grid/block.json | jq '.'