Status: ✅ CLI Ready - Local Development Available
Emma is a system for creating, deploying, and embedding forms into Hugo websites. The CLI is now fully functional for local development and testing.
- Create forms using the interactive CLI (
emma create) - Deploy forms locally for development and testing
- Embed forms in Hugo sites with a simple shortcode
Quick Start:
# Install and initialize
npm install -g @emma/form-builder
emma init
# Create your first form
emma create contact-form
# Deploy locally for testing
emma deploy contact-form-001
# Preview in browser
emma preview contact-form-001Hugo Integration:
{{< embed-form "contact-form-001" >}}✅ CLI Implementation - Fully functional form builder CLI
✅ Local Development - Complete local deployment simulation
✅ Form Builder - Interactive form creation with 13+ field types
✅ Bundle Generation - Self-contained JavaScript bundles
✅ Test Coverage - Comprehensive test suite with 50+ tests
⏳ Production Deployment - Cloudflare integration pending
emma/
├── packages/
│ ├── form-builder/ → CLI tool for creating forms
│ ├── api-worker/ → Cloudflare Worker (handles submissions)
│ ├── form-renderer/ → Client-side JS (renders forms)
│ └── hugo-module/ → Hugo shortcode integration
├── shared/ → Shared TypeScript types
├── docs/ → All documentation
├── examples/ → Sample form configs
└── migrations/ → Database schemas
- Quick Start Guide - Get running in 5 minutes
- Developer Guide - Complete development documentation
- 00-mvp-embeddable-forms.md - Project vision
- 02-technical-architecture.md - Technical architecture
- FOUNDATION-SUMMARY.md - Implementation progress
- Hugo Integration - Embedding forms in Hugo
- Cloudflare Infrastructure - Workers, D1, R2 setup
- Field Types - All 13 supported field types
- API Reference - REST API documentation
- Troubleshooting - Common issues & solutions
# One-time setup
emma init
# Create a form interactively
emma create my-contact-form
# Follow prompts to add fields, validation, themes
# Build the form bundle
emma build my-contact-form-001
# Deploy to local development server
emma deploy my-contact-form-001
# Preview in browser
emma preview my-contact-form-001emma init- Initialize Emma configurationemma create <name>- Create new form interactivelyemma list [--detailed]- List all formsemma build <form-id>- Build form JavaScript bundleemma deploy <form-id>- Deploy to local development serveremma preview <form-id>- Open form in browseremma delete <form-id>- Delete a form
CLI creates form schema (YAML)
↓
Build generates JS bundle
↓
Deploy starts local server
↓
Hugo site embeds form
↓
Visitor fills & submits
↓
Data logged locally
- Text Inputs: text, email, textarea, number, tel, url
- Selection: select dropdown, radio buttons, checkboxes
- Date/Time: date, time, datetime-local
- Special: hidden fields for tracking
- ✅ Interactive form creation with validation
- ✅ 13+ field types with options and validation rules
- ✅ Theme system (default, minimal)
- ✅ Honeypot spam protection
- ✅ Local development server
- ✅ Form preview and testing
- ✅ Hugo shortcode integration ready
For efficient development with automatic rebuilding:
# Watch core packages (form-builder, form-renderer, shared, provider-cloudflare)
yarn dev:core
# Watch API worker (Cloudflare Worker)
yarn dev:api
# Watch website (Hugo site)
yarn dev:website# Install and build CLI
cd packages/form-builder
yarn install && yarn build
# Run tests
yarn test
# Install globally for development
npm link
# Work on other packages
cd ../form-renderer && yarn dev
cd ../api-worker && yarn dev
cd ../shared && yarn devReal working example with the CLI:
# 1. Initialize (one-time setup)
$ emma init
✓ Emma CLI initialized successfully!
# 2. Create a form interactively
$ emma create contact-form
? Form display name: Contact Form
? Select a theme: default
? Submit button text: Send Message
📋 Adding form fields...
? Add field 1: Text Input > Your Name (required)
? Add field 2: Email > Email Address (required)
? Add field 3: Textarea > Message (required)
? Add field 4: ✅ Done adding fields
? Enable spam protection (honeypot)? Yes
✓ Form created: contact-form-001
# 3. Build and deploy locally
$ emma build contact-form-001
✓ Form bundle built successfully
$ emma deploy contact-form-001
✓ Form deployed successfully
Form URL: http://localhost:3333/forms/contact-form-001
API Endpoint: http://localhost:3333/api/submit/contact-form-001
# 4. Preview and test
$ emma preview contact-form-001
🌐 Opening in browser...
# 4. Preview and test in browser
$ emma preview contact-form-001
🌐 Opening in browser...
# 5. Use in Hugo
{{< embed-form "contact-form-001" >}}# Install dependencies
yarn install
# Build all packages
yarn build
# Run tests
yarn test
# Lint code
yarn lint
# Format code
yarn format
# Type check
yarn typecheck- form-builder depends on:
shared/types,shared/schema - api-worker depends on:
shared/types - form-renderer depends on:
shared/types - hugo-module - No dependencies (plain Hugo templates)
- Check the docs in
/docs - Look at example forms in
/examples - Read package READMEs
- Review the technical architecture
- Read MVP document (00-mvp-embeddable-forms.md)
- Understand the architecture (02-technical-architecture.md)
- Review the package you'll work on
- Understand the data flow
- Know where to update docs if needed
- Simple - Easy for Hugo users to integrate
- Fast - Small bundle sizes, edge deployment
- Secure - Spam protection, rate limiting, validation
- Flexible - Themeable, customizable
- Reliable - Edge computing, global availability