Introduction to BlocksWeb

BlocksWeb is a visual CMS framework for React that bridges the gap between developer control and content team autonomy. It combines the flexibility of a headless CMS with the ease of use of a visual page builder.

What is BlocksWeb?

BlocksWeb allows developers to build React components that non-technical users can manage through a visual editor. Think of it as giving your marketing team WordPress-like editing capabilities while you maintain full control over the codebase with modern React patterns.

Key Features

• Visual Page Builder - Drag-and-drop interface for building pages
• Component System - Create reusable React components with editable properties
• Headless CMS - Manage structured content with flexible collections
• Multi-Language Support - Built-in internationalization with per-block translations
• Asset Management - Upload, crop, and organize images
• A/B Testing - Visual test builder with analytics
• Type-Safe - Full TypeScript support throughout
• Framework Flexible - Works with Next.js 11-15, App Router, or Pages Router

How It Works

BlocksWeb operates on a simple principle: Components + Schema = Editable Blocks

1. You Build Components

Create standard React components with TypeScript:

import { IBlockswebComponent } from '@blocksweb/core';

const CallToAction: IBlockswebComponent = ({ title, buttonText, buttonUrl }) => {
  return (
    <div className="cta">
      <h2>{title}</h2>
      <a href={buttonUrl}>{buttonText}</a>
    </div>
  );
};

2. You Define the Schema

Attach a schema that describes what's editable:

CallToAction.schema = {
  displayName: 'Call to Action',
  options: [
    { type: 'text', name: 'title', label: 'Title', default: 'Ready to get started?' },
    { type: 'text', name: 'buttonText', label: 'Button Text', default: 'Sign Up' },
    { type: 'text', name: 'buttonUrl', label: 'Button URL', default: '/signup' }
  ]
};

3. Content Teams Edit Visually

Your marketing team can now:

• Add the Call to Action component to any page
• Edit the title, button text, and URL through a visual interface
• See changes in real-time
• Publish when ready

No code required, no developer bottleneck.

When to Use BlocksWeb

BlocksWeb is perfect for:

• Marketing Websites - Let marketing teams update landing pages, pricing, and content without waiting for developers
• E-commerce Sites - Manage product pages, collections, and promotional content with visual tools
• Content Platforms - Build blogs, documentation sites, or knowledge bases with structured content
• Multi-Brand Sites - Manage multiple sites with shared components and isolated content
• Agency Projects - Deliver sites where clients can manage content independently

When NOT to Use BlocksWeb

BlocksWeb might not be the best fit if:

• You're building a purely static site (consider a static site generator)
• You have no need for content management (just use React)
• You need a fully open-source solution (BlocksWeb requires a paid plan for production)
• Your content team is comfortable editing markdown files in GitHub

Comparison with Other Solutions

Feature	BlocksWeb	React Bricks	Builder.io	WordPress + ACF
React Components	✅ Native	✅ Native	⚠️ Wrapped	❌ PHP
TypeScript	✅ Full Support	✅ Full Support	⚠️ Partial	❌ No
Visual Editor	✅ Yes	✅ Yes	✅ Yes	✅ Yes
Code Ownership	✅ Full Control	✅ Full Control	❌ Locked In	⚠️ Limited
Next.js App Router	✅ Yes	✅ Yes	⚠️ Limited	❌ No
Collections/CMS	✅ Built-in	⚠️ Limited	✅ Yes	✅ Yes
Self-Hosting	✅ Yes	❌ No	❌ No	✅ Yes
Performance	⚡ Fast	⚡ Fast	⚠️ Variable	🐌 Slower

Architecture Overview

BlocksWeb consists of three main parts:

1. Core Package (@blocksweb/core)

Provides React components, hooks, and TypeScript types for building BlocksWeb applications.

2. Visual Editor

A browser-based editor where content teams manage pages, upload assets, and configure components.

3. Cloud API (or Self-Hosted)

Stores page data, assets, and content. Can be hosted on BlocksWeb Cloud or self-hosted.

┌─────────────────┐
│  Next.js App    │
│  (Your Code)    │
└────────┬────────┘
         │ imports
         ↓
┌─────────────────┐      ┌──────────────────┐
│ @blocksweb/core │ ←───→│  Visual Editor   │
│   (Package)     │      │  (Browser-Based) │
└────────┬────────┘      └────────┬─────────┘
         │                        │
         └────────────────────────┘
                    ↓
         ┌──────────────────┐
         │  BlocksWeb API   │
         │ (Cloud/Self-Host)│
         └──────────────────┘

What's Next?

Ready to build your first BlocksWeb application? Continue to the Quick Start guide to create your first project in under 5 minutes.

Or explore:

• Installation Guide - Detailed setup instructions
• Your First Component - Build a complete component
• Project Structure - Understand the file organization