@bagelink/blox

Blox is a Vue 3 library for building drag-and-drop page builders and managing static data for web applications. It provides a complete solution for creating external preview systems and rendering dynamic page content.

Features

• 🎨 Page Builder Integration - Full support for drag-and-drop page building
• 📄 Static Page Management - Manage JSON-based static page data
• 🔌 Component Registry - Flexible component registration system
• 📡 Communication System - Built-in messaging for builder-preview communication
• 🎯 Type-Safe - Full TypeScript support
• 🖼️ Base Components - Pre-built components (Button, Text, Image, etc.)
• 📱 Responsive - Mobile and desktop support

Installation

npm install @bagelink/blox
# or
pnpm add @bagelink/blox
# or
yarn add @bagelink/blox

@bagelink/blox

Blox is a Vue 3 library for building drag-and-drop page builders and managing static data for web applications. It provides a complete solution for creating external preview systems and rendering dynamic page content.

Features

• 🎨 Page Builder Integration - Full support for drag-and-drop page building
• 📄 Static Page Management - Manage JSON-based static page data
• 🔌 Component Registry - Flexible component registration system
• 📡 Communication System - Built-in messaging for builder-preview communication
• 🎯 Type-Safe - Full TypeScript support
• 🖼️ Base Components - Pre-built components (Button, Text, Image, etc.)
• 📱 Responsive - Mobile and desktop support

Installation

npm install @bagelink/blox vue-router
# or
pnpm add @bagelink/blox vue-router
# or
yarn add @bagelink/blox vue-router

Quick Start (Recommended)

The simplest way to set up Blox in your Vue application:

// main.ts
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import { createBlox, ButtonConfig, TextConfig, TitleConfig } from '@bagelink/blox'
import '@bagelink/blox/dist/blox.css'

import App from './App.vue'

const app = createApp(App)
const router = createRouter({
	history: createWebHistory(),
	routes: [
		// Your app routes
	],
})

// Create and configure Blox
const blox = createBlox()
blox.registerComponents([ButtonConfig, TextConfig, TitleConfig]).registerRoutes(router)

app.use(blox)
app.use(router)
app.mount('#app')

That's it! Preview routes are now available at:

• /blox/preview/:pageId? - External preview with editor communication
• /blox/render/:pageId? - Static page rendering

With Custom Components

import { createBlox, createComponentConfig, ButtonConfig } from '@bagelink/blox'
import MyHeroSection from './components/MyHeroSection.vue'

const MyHeroConfig = createComponentConfig({
	id: 'MyHero',
	label: 'Hero Section',
	icon: 'hero_section',
	component: MyHeroSection,
	content: [
		{
			type: 'text',
			key: 'title',
			label: 'Hero Title',
			defaultValue: 'Welcome!',
		},
	],
})

const blox = createBlox()
blox.registerComponents([ButtonConfig, MyHeroConfig]).registerRoutes(router)

app.use(blox)

Available Built-in Component Configs

Import these configs to register built-in components:

• ButtonConfig - Customizable button/link
• TextConfig - Rich text content
• TitleConfig - Heading with optional subtitle
• ImageConfig - Responsive image
• SpacerConfig - Vertical spacing
• ContainerConfig - Content container with max-width

For more examples, see SETUP_EXAMPLE.md.

Alternative Setup (Legacy)

1. Register Base Components

import { createApp } from 'vue'
import { registerBaseComponents } from '@bagelink/blox'

const app = createApp(App)

// Register all base components
registerBaseComponents(app)

app.mount('#app')

2. Use the RenderPage Component

<template>
	<RenderPage :page-data="pageData" />
</template>

<script setup lang="ts">
import { RenderPage } from '@bagelink/blox'

const pageData = {
  components: [...],
  pageSettings: {...}
}
</script>

3. Use ExternalPreview for Page Builder

<template>
	<ExternalPreview :origin="editorOrigin" />
</template>

<script setup lang="ts">
import { ExternalPreview } from '@bagelink/blox'

const editorOrigin = 'https://your-editor.com'
</script>

Core Concepts

Component Registry

Register your custom components to make them available in the page builder:

import { registerComponent, registerComponents } from '@bagelink/blox'
import MyButton from './MyButton.vue'

// Register a single component
registerComponent('Button', MyButton)

// Or register multiple components at once
registerComponents({
	Button: MyButton,
	Hero: MyHero,
	Text: MyText,
})

Communication System

Blox includes a built-in communication system for coordinating between the builder and preview:

import { createCommunicationBridge } from '@bagelink/blox'

// Create a communication bridge
const bridge = createCommunicationBridge({
	origin: 'https://editor.com',
	targetWindow: window.parent,
})

// Listen for messages
bridge.on('update', ({ data }) => {
	console.log('Received update:', data)
})

// Send messages
bridge.send('ready', { components: ['Button', 'Hero'] })

Styling Utilities

Use the built-in styling utilities to apply consistent styles:

import { generateBlockStyles, getResponsiveClasses } from '@bagelink/blox'

const styles = generateBlockStyles(blockData, false)
const classes = getResponsiveClasses(blockData)

Base Components

The library includes these pre-built components:

• Button - Customizable button with variants
• Container - Layout container with spacing
• Image - Responsive image component
• Spacer - Vertical/horizontal spacing
• Text - Rich text content
• Title - Heading component

API Reference

Registry API

registerComponent(type: string, component: ComponentConstructor)

Register a single component.

import { registerComponent } from '@bagelink/blox'
import MyButton from './MyButton.vue'

registerComponent('Button', MyButton)

Parameters:

• type - The block type identifier (e.g., 'Button', 'Hero')
• component - Vue component constructor or async import

registerComponents(components: ComponentRegistry)

Register multiple components at once.

import { registerComponents } from '@bagelink/blox'

registerComponents({
	Button: MyButton,
	Hero: MyHero,
	Text: MyText,
})

Parameters:

• components - Object mapping type names to components

getComponent(type: string): ComponentConstructor | undefined

Get a registered component by type.

const ButtonComponent = getComponent('Button')

hasComponent(type: string): boolean

Check if a component type is registered.

if (hasComponent('Button')) {
	// Button is registered
}

getAllComponents(): ComponentRegistry

Get all registered components.

const allComponents = getAllComponents()

unregisterComponent(type: string)

Remove a component from the registry.

unregisterComponent('Button')

clearRegistry()

Remove all registered components.

clearRegistry()

getRegisteredTypes(): string[]

Get array of all registered type names.

const types = getRegisteredTypes()
// ['Button', 'Hero', 'Text']

createNamespacedRegistry(namespace: string)

Create a namespaced registry for multi-tenant scenarios.

const siteA = createNamespacedRegistry('site-a')
siteA.register('Button', ButtonA)

const siteB = createNamespacedRegistry('site-b')
siteB.register('Button', ButtonB)

Returns: Object with methods:

• register(type, component) - Register to namespace
• get(type) - Get from namespace
• getAll() - Get all from namespace

Communication API

createCommunicationBridge(config: CommunicationConfig): CommunicationBridge

Create a communication bridge for postMessage communication.

import { createCommunicationBridge } from '@bagelink/blox'

const bridge = createCommunicationBridge({
	origin: 'https://editor.com',
	targetWindow: window.parent,
})

Parameters:

• config.origin - Allowed origin (string or '*')
• config.targetWindow - Target window (default: window.parent)
• config.onMessage - Optional global message handler

CommunicationBridge.on(type: MessageType, handler: MessageHandler): () => void

Register a message handler.

const unsubscribe = bridge.on('update', ({ data }) => {
	console.log('Received update:', data)
})

// Later: unsubscribe()

Parameters:

• type - Message type or '*' for all messages
• handler - Handler function

Returns: Unsubscribe function

CommunicationBridge.off(type: MessageType, handler: MessageHandler)

Unregister a message handler.

bridge.off('update', myHandler)

CommunicationBridge.send(type: MessageType, message?: any, data?: any)

Send a message to the target window.

bridge.send('focus', 'block-123')
bridge.send('update', null, { components: [...] })

Parameters:

• type - Message type
• message - Optional message payload
• data - Optional data payload

CommunicationBridge.destroy()

Clean up and remove all listeners.

bridge.destroy()

sendMessage(type, message?, targetWindow?, origin?)

Send a one-off message without creating a bridge.

import { sendMessage } from '@bagelink/blox'

sendMessage('ready', { components: ['Button', 'Hero'] })

Renderer API

initializePage(pageData: PageData): Promise<void>

Initialize a page with all settings and assets.

import { initializePage } from '@bagelink/blox'

await initializePage(pageData)

What it does:

• Injects responsive CSS
• Applies page settings
• Loads Google Fonts
• Injects custom code

injectResponsiveCSS()

Inject the responsive CSS system.

import { injectResponsiveCSS } from '@bagelink/blox'

injectResponsiveCSS()

injectCode(code: string | undefined, target: 'head' | 'body')

Inject custom code into head or body.

injectCode('<script>console.log("Hello")</script>', 'head')

loadGoogleFont(fontName: string): Promise<void>

Load a Google Font.

await loadGoogleFont('Roboto')

loadComponentFonts(components: ComponentData[]): Promise<void>

Load all fonts used in components.

await loadComponentFonts(pageData.components)

applyGlobalFont(fontName: string)

Apply a font globally to the page.

applyGlobalFont('Inter')

applyPageSettings(pageData: PageData)

Apply all page settings to the document.

applyPageSettings(pageData)

Styles API

generateBlockStyles(data: Record<string, any>, isMobile?: boolean): Record<string, string>

Generate CSS styles from block data.

import { generateBlockStyles } from '@bagelink/blox'

const styles = generateBlockStyles(blockData, false)
// { 'margin-top': '2rem', 'padding': '1rem', ... }

Parameters:

• data - Block data object
• isMobile - Whether to use mobile overrides (default: false)

Returns: CSS styles object

getResponsiveClasses(data: Record<string, any>): string[]

Get responsive CSS classes for a block.

const classes = getResponsiveClasses(blockData)
// ['blox-block', 'responsive-colors', 'full-width-mobile']

getResponsiveCSS(): string

Get the responsive CSS to inject.

const css = getResponsiveCSS()

Normalizer API

normalizeComponentData(data: Record<string, any>): Record<string, any>

Normalize component data (convert string booleans, numbers, etc.).

import { normalizeComponentData } from '@bagelink/blox'

const normalized = normalizeComponentData({
	width: '800',
	fullWidth: 'true',
	title: 'Hello',
})
// { width: 800, fullWidth: true, title: 'Hello' }

deepClone<T>(obj: T): T

Deep clone an object.

const cloned = deepClone(originalData)

deepMerge(target: any, source: any): any

Deep merge two objects.

const merged = deepMerge(defaults, customSettings)

Components

ExternalPreview

Preview component for external sites.

<ExternalPreview :origin="editorOrigin" :initial-page-data="pageData" />

Props:

• origin?: string - Allowed editor origin (default: '*')
• initialPageData?: PageData - Optional initial page data

Events: Communicates via postMessage with these message types:

• ready - Sent when preview is ready
• focus - Sent when block is focused
• highlight - Sent when block is highlighted

RenderPage

Production render component.

<RenderPage :page-data="pageData" :mobile-breakpoint="910" />

Props:

• pageData: PageData - Required page data to render
• mobileBreakpoint?: number - Window width for mobile (default: 910)

TypeScript Types

ComponentData

interface ComponentData {
	id: string
	type: string
	data: Record<string, any>
}

PageData

interface PageData {
	id?: string
	components: ComponentData[]
	pageSettings?: PageSettings
	header_code?: string
	body_code?: string
	language?: Record<string, any>
}

PageSettings

interface PageSettings {
	selectedGoogleFont?: string
	pageLanguage?: string
	pageDirection?: 'ltr' | 'rtl'
	additionalHeadCode?: string
	additionalBodyCode?: string
	customFavicon?: string
	customOgImage?: string
	customKeywords?: string
	customRobotsMeta?: string
	customAnalyticsCode?: string
	disableGlobalHeadCode?: boolean
	disableGlobalBodyCode?: boolean
	disableGoogleAnalytics?: boolean
	disableFacebookPixel?: boolean
}

GlobalSettings

interface GlobalSettings {
	selectedGoogleFont?: string
	pageLanguage?: string
	pageDirection?: 'ltr' | 'rtl'
	globalHeadCode?: string
	globalBodyCode?: string
	favicon?: string
	ogImage?: string
	siteKeywords?: string
	googleAnalyticsId?: string
	facebookPixelId?: string
}

MessageType

type MessageType =
	| 'ready'
	| 'update'
	| 'focus'
	| 'highlight'
	| 'preview'
	| 'meta'
	| 'delete'
	| 'disableLinks'
	| 'newBlock'

EditorMessage

interface EditorMessage {
	type: MessageType
	message?: any
	data?: any
	isMobile?: boolean
}

BlockProps

interface BlockProps {
	isMobile?: boolean
	[key: string]: any
}

StyleConfig

interface StyleConfig {
	// Spacing
	marginTop?: number
	marginBottom?: number
	marginTopMobile?: number
	marginBottomMobile?: number
	padding?: number
	paddingMobile?: number

	// Width
	width?: number
	widthMobile?: number
	widthPercent?: number
	widthPercentMobile?: number
	fullWidth?: boolean
	fullWidthMobile?: boolean

	// Colors
	backgroundColor?: string
	backgroundColorMobile?: string
	textColor?: string
	textColorMobile?: string

	// Border
	borderWidth?: number
	borderWidthMobile?: number
	borderStyle?: string
	borderStyleMobile?: string
	borderColor?: string
	borderColorMobile?: string
	borderRadius?: number
	borderRadiusMobile?: number

	// Typography
	fontFamily?: string
	fontFamilyMobile?: string
	center?: boolean
	centerMobile?: boolean

	// Effects
	shadowType?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'custom'
	shadowTypeMobile?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'custom'
	zIndex?: number
	zIndexMobile?: number

	// Visibility
	showDesktop?: boolean
	showMobile?: boolean

	// Custom
	customId?: string
	customCSS?: string
}

Message Protocol

Editor → Preview

update

Update components data.

{
  type: 'update',
  data: ComponentData[],
  isMobile: boolean
}

focus

Focus a specific block.

{
  type: 'focus',
  message: 'block-id-123'
}

highlight

Highlight a specific block.

{
  type: 'highlight',
  message: 'block-id-123'
}

preview

Toggle preview mode.

{
  type: 'preview',
  message: true | false
}

disableLinks

Disable link navigation.

{
  type: 'disableLinks',
  message: true | false
}

Preview → Editor

ready

Preview is ready.

{
  type: 'ready',
  message: {
    registeredTypes: string[]
  }
}

focus

User focused a block.

{
  type: 'focus',
  message: 'block-id-123'
}

highlight

User highlighted a block.

{
  type: 'highlight',
  message: 'block-id-123'
}

delete

User wants to delete a block.

{
  type: 'delete',
  message: 'block-id-123'
}

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT © Bagel Studio

Links

• GitHub Repository
• Documentation
• Issues