HeyForm

HeyForm is an open‑source, self‑hosted platform that turns static surveys into conversational experiences. From a technical standpoint it is essentially a full‑stack, micro‑service oriented application that exposes both an internal API for form definition and a public API for embed rendering. The core idea is to allow developers to programmatically create, modify, and consume form data while keeping the user interface lightweight and embeddable across any web page.

Architecture & Technical Stack

• Front‑end: A React SPA (webapp) built with TypeScript, leveraging react-router for navigation and a custom form‑renderer library that interprets JSON schemas into interactive UI components. The renderer supports advanced input types (file uploads, picture choices) and conditional logic via a declarative rules engine.
• Back‑end: A Node.js/Express server (server) written in TypeScript that exposes REST endpoints for CRUD operations on forms, submissions, and analytics. It integrates with a PostgreSQL database (via Prisma) for persistence, and Redis for caching submission counts and analytics hits.
• Shared Libraries: shared-types-enums provides a single source of truth for data contracts, ensuring type safety across both client and server. answer-utils contains business logic for validating and sanitizing submissions, while utils hosts common helpers.
• Deployment: The project is container‑ready. Dockerfiles exist for both the server and webapp, and a Helm chart (or Docker Compose) can spin up the entire stack on Kubernetes or any OCI‑compatible runtime. The embed package ships as a minified JS bundle that can be dropped into any page, communicating with the server via HTTPS and WebSocket for real‑time updates.

Core Capabilities & APIs

• Form Definition API: Create, update, and delete forms via JSON payloads. Each form is a tree of questions with metadata (type, validation rules, conditional logic).
• Submission API: Secure endpoints that accept multipart/form-data for file uploads and JSON for other fields. Submissions are stored atomically, with optional webhook triggers.
• Analytics API: Exposes metrics such as completion rate, drop‑off points, and custom event hooks. These can be consumed by external dashboards or BI tools.
• Embed SDK: A lightweight JavaScript library (embed) that handles form rendering, state persistence, and submission flow. It supports theming via CSS variables and custom hooks for event handling.

Deployment & Infrastructure

HeyForm’s self‑hosting path is designed for scalability:

• Horizontal scaling of the Node server behind a load balancer (NGINX or Traefik).
• Stateless React build files served via CDN for global reach.
• PostgreSQL can be sharded or replicated; Redis supports clustering for high throughput.
• Docker Compose or Kubernetes manifests allow zero‑downtime rollouts. The repository includes a one‑click Railway template for rapid prototyping.

Integration & Extensibility

• Webhooks: Trigger on submission or form lifecycle events, enabling integration with Zapier, Make.com, or custom microservices.
• SDK Hooks: The embed library exposes onSubmit, onError, and onRender callbacks, allowing developers to inject analytics or modify UI behavior.
• Custom Themes: Expose CSS variables and a customCSS field in the form definition, giving full control over appearance without touching source code.
• Plugin Architecture: While not fully plugin‑driven, the modular packages structure encourages adding new input types or analytics modules by extending the renderer and server routes.

Developer Experience

• Type Safety: Shared types ensure that form schemas, submissions, and API responses are consistently typed across both client and server.
• Documentation: The official docs cover API endpoints, webhook payloads, and embed usage. Example schemas are available in the shared-types-enums package.
• Community & Support: Active GitHub issues, a Discord channel, and regular releases keep the ecosystem vibrant. Licensing under MIT allows unrestricted commercial use.

Use Cases

1. Enterprise Feedback Loops: Embed conversational surveys in intranet portals, collect data via the API, and push results to internal BI tools.
2. Event Registration: Use conditional logic to tailor questions based on attendee type, and trigger webhook notifications to ticketing systems.
3. Market Research: Deploy quick polls on landing pages, capture responses in real time, and analyze drop‑off rates to refine UX.
4. Compliance Checklists: Build dynamic forms that enforce mandatory fields and auto‑generate audit logs via the analytics API.

Advantages Over Alternatives

• Self‑hosted Freedom: No vendor lock‑in; full control over data residency and compliance.
• Performance & Flexibility: Lightweight embed script reduces load times; server side can be scaled independently.
• Open Source & Extensible: MIT license and modular codebase allow deep customization, from new input types to custom analytics dashboards.
• Developer‑First APIs: Strong typing, webhook hooks, and a well‑documented SDK make integration painless for full‑stack developers.

In summary, HeyForm offers a robust, modular platform that balances an intuitive UI for end users with a powerful API surface for developers. Its architecture supports scaling, extensibility, and rapid deployment—making it an attractive choice for any organization looking to embed conversational data collection into its own infrastructure.