@bolttech/template-editor

A powerful, drag-and-drop visual template editor built with React, TypeScript, and Craft.js. Create dynamic templates with variables, rich content, and professional layouts - perfect for email templates, landing pages, and dynamic content generation.

✨ Features

• 🎨 Visual Drag & Drop Editor: Intuitive interface for building templates without code
• 📱 Responsive Design: Built-in responsive controls and preview modes
• 🔧 Variable System: Dynamic content with Handlebars-style variables ({{variable}})
• 🧱 Rich Component Library: Text, images, buttons, containers, and dividers
• ⚡ Real-time Editing: See changes instantly as you build
• 📤 Export Options: Download as HTML or PDF with live preview
• 🎯 TypeScript Support: Full type safety and excellent developer experience
• 🔒 Shadow DOM Isolation: Styles and components are fully encapsulated

📦 Installation

NPM

npm install @bolttech/template-editor

Yarn

yarn add @bolttech/template-editor

Peer Dependencies

The library requires these peer dependencies to be installed in your project:

# For React 16.8+, 17, 18 or 19
npm install react react-dom

Note: All other dependencies (monaco-editor, handlebars, react-icons, htmlparser2, sanitize-html) are now included automatically with the library installation.

🚀 Quick Start

Basic Usage

import React from 'react';

import { TemplateEditor } from '@bolttech/template-editor';
import '@bolttech/template-editor/style.css';

function App() {
  return (
    <div style={{ height: '100vh' }}>
      <TemplateEditor />
    </div>
  );
}

export default App;

With Variables

import React from 'react';

import { PlaceholderData, TemplateEditor } from '@bolttech/template-editor';
import '@bolttech/template-editor/style.css';

const placeholders: PlaceholderData = {
  user: {
    name: {
      key: 'user.name',
      label: 'User Name',
      value: 'John Doe',
      type: 'text',
    },
    email: '[email protected]',
    profile: {
      age: 28,
      verified: true,
    },
  },
  company: {
    name: 'BoltTech',
    address: {
      city: 'São Paulo',
      country: 'Brazil',
    },
  },
  product: {
    name: 'Template Editor',
    price: 99.99,
  },
  campaign: {
    type: {
      key: 'campaign.type',
      label: 'Campaign Type',
      value: 'email',
      type: 'enum',
      options: [
        { label: 'Email Campaign', value: 'email' },
        { label: 'SMS Campaign', value: 'sms' },
        { label: 'Push Notification', value: 'push' },
      ],
    },
    active: true,
  },
};

function App() {
  return (
    <div style={{ height: '100vh' }}>
      <TemplateEditor placeholders={placeholders} />
    </div>
  );
}

📚 API Reference

Props

The TemplateEditor component accepts one optional prop:

| Prop | Type | Description | | -------------- | ----------------- | ------------------------------------------------------------------------ | | placeholders | PlaceholderData | Unified data structure supporting primitives, schemas, and nested values |

Example with Mixed Values

const placeholders: PlaceholderData = {
  // Primitive values (auto-converted to schemas in the UI)
  userName: 'John Doe',
  userEmail: '[email protected]',

  // Nested objects
  company: {
    name: 'ACME Corp',
    address: {
      city: 'New York',
    },
  },

  // Schema with metadata for form controls
  userRole: {
    key: 'userRole',
    label: 'User Role',
    value: 'user',
    type: 'enum',
    options: ['admin', 'user', 'guest'],
  },
};

<TemplateEditor placeholders={placeholders} />;

📋 Need more details? See complete API reference for full TypeScript definitions.

🧱 Built-in Blocks

The editor includes drag & drop components:

• 📝 Text - Rich text with formatting and variables
• 🔘 Button - Interactive buttons with styling
• 🖼️ Image - Responsive images with alt text
• 📦 Box - Layout containers with spacing controls
• 〰️ Divider - Visual separators
• 🔗 Variable - Dynamic content with Handlebars syntax ({{variable.name}})

🎯 Use Cases

Perfect for creating:

• 📧 Email templates - Marketing emails, newsletters, notifications
• 📄 Landing pages - Product launches, campaigns, lead generation
• 📋 Documents - Reports, invoices, certificates
• 🎨 Dynamic content - Personalized content with variables

💡 Want examples? Check docs/ for sample implementations.

📥 Export & Download

The template editor includes powerful export capabilities:

Download as HTML

Export your template as clean, production-ready HTML:

• Standalone HTML files - Complete with embedded styles
• Compiled variables - All {{variable}} placeholders replaced with actual values
• Responsive output - Works across all devices and email clients

Download as PDF

Generate PDF documents from your templates:

• High-quality PDFs - Professional document output
• Live preview - See exactly what you'll get before downloading
• Variable resolution - All placeholders resolved to their current values

Export Options

Access export features through the preview panel:

1. Click the Preview button to see your template with live data
2. Use the Download dropdown to choose your format:
   • HTML - Download as .html file
   • PDF - Download as .pdf document

Both formats automatically compile your template with the current placeholder values, ensuring the exported content matches what you see in the preview.

🎨 Styling

The editor uses Shadow DOM for complete style isolation - no CSS conflicts with your app!

🔧 TypeScript Support

Full TypeScript support included:

import type {
  PlaceholderData,
  PlaceholderSchema,
  PlaceholderValue,
  TemplateEditorProps,
} from '@bolttech/template-editor';
import { PlaceholderUtils } from '@bolttech/template-editor';

🐛 Troubleshooting

Styles not loading?

import '@bolttech/template-editor/style.css';

Peer dependency warnings?

npm install react react-dom

📋 Requirements

• Node.js: ≥16.0
• React: ≥16.8.0 (supports React 16.8, 17, 18, 19)
• TypeScript: ≥4.0 (recommended)

📄 License

MIT License - see the LICENSE file for details.

🧪 Testing

The library includes comprehensive tests to ensure reliability:

# Run tests once
npm run test:run

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run full CI pipeline (lint + test + build)
npm run ci

🔧 Development & Deployment

Pre-commit and Pre-push Hooks

This project uses Husky to ensure code quality:

Pre-commit hooks:

• ✅ Code formatting and linting (via lint-staged)
• ✅ Test execution

Pre-push hooks:

• ✅ Test execution with coverage
• ✅ Build verification

Available Scripts

# Development
npm run dev          # Start development server
npm run preview      # Preview production build

# Code Quality
npm run lint         # Run ESLint
npm run format       # Fix formatting and linting
npm run format:check # Check formatting only

# Testing
npm run test         # Run tests in watch mode
npm run test:run     # Run tests once
npm run test:coverage # Run tests with coverage report
npm run test:watch   # Run tests in watch mode

# Building
npm run build        # Build for production
npm run build -- --mode lib    # Build library only
npm run build -- --mode app    # Build application only

# CI/CD
npm run ci           # Run complete CI pipeline

Docker Support

Build and test in Docker:

# Build with tests included
docker build -f Dockerfile.jenkins -t template-editor .

🤝 Contributing

We welcome contributions! Please see our development guide for details.

🆘 Support

For support, questions, or assistance with the Template Editor, please contact our Shared Services team:

📧 Email: [email protected]

Built with ❤️ by BoltTech for creating beautiful, dynamic templates with ease.