Working with Block Assets

WPBits Block Studio generates several files for each block. This guide explains how to customize these files depending on whether you’re using the free or pro version.

Generated Files

When you create a block, WPBits Block Studio generates:

File	Purpose	Free	Pro
block.json	Block registration metadata	✅	✅
index.js	Editor script (block registration in JS)	✅	✅
template.twig	Frontend template (Twig)	✅	✅
style.css	Frontend styles	✅	✅
editor.css	Editor-only styles	✅	✅
frontend.js	Frontend JavaScript	✅	✅
render.php	Custom render callback	❌	✅ generated
icon.svg	Custom block icon	✅	✅

Files are stored at wp-content/uploads/wpbits-block-studio/<block-name>/ by default.

---

Free Version — Manual File Editing

In the free version, the Template Editor, Styles Editor, and JavaScript Editor are locked. You must edit files directly on the filesystem using your own code editor.

Option A: Local Development with Export/Import

This workflow lets you edit block files in a proper code editor on your local machine, then push the changes to production.

Step 1: Install WPBits Block Studio on a local development environment (or a staging site where you have filesystem access).

Step 2: Create your block and configure attributes via the UI.

Step 3: Navigate to the block’s directory on the filesystem:

wp-content/uploads/wpbits-block-studio/<block-name>/

Edit the files with your code editor:

• template.twig — Block frontend HTML/Twig
• style.css — Frontend styles
• editor.css — Backend editor styles
• frontend.js — Frontend JavaScript

Step 4: Export the block as ZIP from WPBits Block Studio → click Export.

Step 5: On the production site, go to WPBits Block Studio → Settings → Import / Export and upload the ZIP.

Auto-Sync is Always-On

In the free version, auto-sync is always enabled. If you open a block in the editor and save it, the database overwrites any manual file changes.

• To preserve manual edits, avoid re-saving blocks after editing files directly
• If the block gets out of sync, re-import the ZIP to restore your changes

Option B: Direct File Replacement via FTP/SSH

If you have direct server access, you can edit files in place:

1. Connect to your server via FTP/SFTP/SSH
2. Navigate to wp-content/uploads/wpbits-block-studio/<block-name>/
3. Download the files, edit them locally, and upload them back
4. Or edit directly on the server using a terminal editor (vim, nano, etc.)

The same auto-sync constraint applies: if auto-sync is active and the block is saved via the UI, your manual changes will be overwritten. Use this approach when you don’t plan to edit the block through the WordPress admin.

---

Pro Version — Multiple Approaches

Pro users have full inline editors plus additional deployment options.

Option A: Edit via the Admin UI

Pro unlocks writable code editors directly in the WPBits Block Studio admin:

• Template Editor — Edit template.twig and render.php with syntax highlighting, attribute drag-and-drop, and live preview
• Styles Editor — Write custom CSS for style.css and editor.css with syntax highlighting
• JavaScript Editor — Add custom frontend JS to frontend.js

Changes made through the UI are saved to the database and automatically synced to the filesystem.

Option B: Change Output Directory — Theme Integration

Instead of blocks going to the default uploads directory, you can point WPBits Block Studio to generate blocks directly inside your theme.

1. Go to WPBits Block Studio → Settings
2. Find the Output Directory field
3. Enter a path relative to your theme (e.g., blocks/) or an absolute path

Blocks will now be generated inside your theme directory:

wp-content/themes/your-theme/
└── blocks/
    ├── feature-card/
    │   ├── block.json
    │   ├── template.twig
    │   ├── style.css
    │   └── ...
    └── ...

Recommended: Use a child theme so theme updates don’t overwrite your blocks. Configure the output directory to point to a folder inside your child theme.

Benefits of theme integration:

• Block files are part of your theme — update the theme to update blocks on production
• Version control friendly — blocks live with your theme code in git
• CI/CD compatible — deploy block changes through your existing deployment pipeline
• No separate export/import steps needed

Option C: Git + CI/CD Pipeline

With the output directory set to your theme and auto-sync enabled:

1. Edit blocks via the UI (or manually, with auto-sync toggled as needed)
2. Changes are automatically written to files in your theme directory
3. Commit and push to your git repository
4. Deploy through your CI/CD pipeline (e.g., GitHub Actions, deploy to production server)

This works especially well with dockerized WordPress development environments — build your blocks, commit the changes, and deploy automatically.

Auto-Sync Toggle

Pro users can control auto-sync per-block:

• Enabled (default) — Files stay in sync with the database. UI edits are immediately written to files.
• Disabled — You can edit files manually without the database overwriting them. When you’re done, you can re-enable auto-sync or manually trigger a regeneration.

This gives you the flexibility to use the UI for quick edits and manual file access for complex changes, switching between them as needed.

Comparison

Approach	Free	Pro
Edit templates via admin UI	❌ Locked	✅ Full editor
Edit CSS via admin UI	❌ Locked	✅ Full editor
Edit JS via admin UI	❌ Locked	✅ Full editor
Export/Import ZIP workflow	✅	✅
FTP/SSH direct file edits	✅	✅
Point output to theme directory	❌	✅
Child theme integration	❌	✅
Git version control workflow	Manual only	Automated with auto-sync
CI/CD pipeline support	Limited	Full
Per-block auto-sync toggle	❌ Always-on	✅ Configurable

Next Steps

• Creating & Managing Blocks — Add/remove attributes manually
• Sync Status — Monitor block synchronization
• Pro Features Overview — All Pro features