heyform: Open-Source Form Builder for Self-Hosted Surveys

heyform/heyform: Open-Source Form Builder for Self-Hosted Surveys

Building forms that don't feel like forms is harder than it looks. Most developers have wrestled with rigid survey tools that force awkward UX patterns, lock data behind proprietary APIs, or balloon costs as submission volumes grow. For teams that need conversational, logic-driven forms without surrendering control of their data, the options narrow quickly. heyform/heyform enters this gap as an open-source form builder designed for self-hosting, with conditional logic, deep customization, and a modern TypeScript stack. This article breaks down what the project offers, how to run it, and whether it fits your stack.

What is heyform/heyform?

heyform/heyform is an open-source form builder aimed at small business use cases, though its architecture appeals to developers who want full control over form infrastructure. The project lives at https://github.com/heyform/heyform and carries 8,881 stars and 687 forks as of its last commit on July 14, 2026. It is written primarily in TypeScript and released under the GNU Affero General Public License v3.0 (AGPL-3.0).

The project is maintained by what the README describes as "the passionate duo behind HeyForm" — a small team offering both the open-source core and a hosted cloud service at my.heyform.net. This dual model is common in open-source SaaS: the core project remains freely available for self-hosting, while revenue from managed hosting funds continued development.

Technically, heyform/heyform is a monorepo organized into seven packages: answer-utils for form submission utilities, embed for JavaScript^{↗ Bright Coding Blog} embedding, form-renderer for the form rendering engine, shared-types-enums for common type definitions, utils for shared helpers, server for the Node.js backend, and webapp for the React^{↗ Bright Coding Blog} frontend. This separation matters for developers who might want to reuse components — the embed library or form renderer, for instance — in custom applications without pulling in the full stack^{↗ Bright Coding Blog}.

The AGPL-3.0 license is worth noting explicitly. Unlike permissive licenses like MIT, AGPL requires that any network-accessible instance of the software also make its source code available to users. This affects deployment decisions for teams building proprietary services on top of heyform/heyform — you'll need to understand the license obligations before embedding it in a closed product.

Key Features

heyform/heyform organizes its capabilities into three areas: form construction, visual customization, and data analysis. Each has technical depth that goes beyond typical "drag-and-drop" form builders.

Form Construction: The input type coverage is extensive — standard fields (text, email, phone) join specialized controls like picture choices, date pickers, and file uploads. More significantly, the tool supports conditional logic and URL redirections, enabling dynamic form flows where subsequent questions adapt based on prior answers. This is the "conversational" behavior referenced in the project's positioning: forms that feel more like guided dialogues than static questionnaires. Webhook integrations and connections to Zapier and Make.com extend this into automation pipelines.

Visual Customization: Beyond basic theme controls (fonts, colors, backgrounds), heyform/heyform exposes custom CSS for deeper visual overrides. This matters for teams with strict brand guidelines or those embedding forms into existing design systems where pixel-perfect consistency is required.

Data Analysis: The analytics layer tracks completion rates and drop-off points — critical metrics for optimizing form conversion. Results export to CSV for downstream processing in analytics tools or data warehouses. The README notes these features are actively maintained with "regular updates, including bug fixes, new features, and performance improvements."

Use Cases

Customer Feedback & NPS Surveys: The conditional logic shines here — a low satisfaction score can trigger follow-up questions about specific pain points, while promoters skip to a referral request. The CSV export feeds directly into BI tools for trend analysis.

Product Onboarding Flows: Teams building self-serve products can embed heyform/heyform's renderer to collect user preferences during signup, then use webhook integrations to provision features or trigger personalized email sequences via Zapier.

Internal Data Collection: For organizations with data residency requirements, self-hosted heyform/heyform keeps submission data on infrastructure you control. The AGPL license aligns with transparency mandates common in public sector and healthcare-adjacent projects.

Embedded Lead Generation: The embed package provides a JavaScript library for injecting forms into marketing sites without iframe limitations. Custom CSS ensures visual continuity with parent pages.

Quiz & Assessment Tools: Picture choices and conditional branching support interactive quizzes with scored outcomes — useful for education platforms or pre-screening workflows.

Installation & Setup

heyform/heyform offers three paths: hosted cloud, one-click deployment, and local development. The hosted route requires no setup — sign up at my.heyform.net — but sacrifices control. For self-hosting, the project provides multiple deployment targets.

One-Click Deployments:

The README lists four platform-specific buttons:

Zeabur: Deploy template
Sealos: Deploy on Sealos
RepoCloud: Deploy to RepoCloud
Alibaba Cloud: Deploy on Alibaba Cloud

These handle infrastructure provisioning but may lock you into platform-specific configurations. Review each template's resource requirements before deploying.

Local Development:

For full control, clone and run locally following the official documentation. The monorepo structure implies you'll need Node.js and a package manager supporting workspaces (npm, yarn, or pnpm). The server package requires a running Node.js environment; the webapp package is a React application likely needing a build step before serving.

The README does not specify exact prerequisite versions — consult the local development docs for current Node.js requirements and database dependencies. The server package likely requires MongoDB or PostgreSQL^{↗ Bright Coding Blog} for persistence, though this is not explicitly stated in the README.

Real Code Examples

The README contains minimal inline code, reflecting a documentation strategy that defers to external guides. What follows is extracted directly from the source material, with explicit framing where the documentation is thin.

Project Structure Reference:

The monorepo layout is the most concrete "code" present in the README:

.
└── packages
    ├── answer-utils       (form submission utils for server and webapp)
    ├── embed              (form embed javascript library)
    ├── form-renderer      (form rendering library)
    ├── shared-types-enums (shared types/enums for server and webapp)
    ├── utils              (common utils for server and webapp)
    ├── server             (node server)
    └── webapp             (react webapp)

This structure reveals intentional separation of concerns. The embed and form-renderer packages are designed for external consumption — you could theoretically import form-renderer into a custom React application and feed it your own form definitions, while embed provides a framework-agnostic JavaScript API for non-React contexts.

Embedding Example (Inferred from Package Purpose):

The embed package's existence implies usage like:

<!-- Hypothetical: actual API may differ -->
<script src="path/to/heyform-embed.js"></script>
<div id="my-form"></div>
<script>
  HeyForm.render({
    formId: 'your-form-id',
    target: '#my-form'
  });
</script>

Important caveat: The README does not provide actual embed API code. The above illustrates the package's documented purpose only. For production use, consult the embed package source or documentation.

Server Package Note:

The server package is a Node.js application. Based on standard TypeScript/Node patterns and the project's stack, local development likely involves:

# Install dependencies at root
npm install

# Build shared packages
npm run build --workspace=packages/shared-types-enums
npm run build --workspace=packages/utils
npm run build --workspace=packages/answer-utils

# Start server and webapp (commands inferred from typical monorepo setups)
npm run dev --workspace=packages/server
npm run dev --workspace=packages/webapp

Again, these commands are reconstructed from common patterns — the README does not list them explicitly. The local development docs are the authoritative source.

Advanced Usage & Best Practices

Component Reuse: The monorepo structure invites selective adoption. If you need form rendering without the full platform, import @heyform/form-renderer directly. This reduces bundle size and avoids pulling in server-side dependencies.

Theming Strategy: Start with the built-in theme controls for rapid iteration, then layer custom CSS for production polish. The CSS injection point is likely at the form renderer level — inspect the DOM structure after initial render to identify stable class names.

Data Pipeline Design: Webhook integrations should include idempotency handling. heyform/heyform's server will retry failed webhook deliveries, so your endpoints must gracefully handle duplicate payloads. Store processed webhook IDs to prevent double-processing.

License Compliance: AGPL-3.0's network clause triggers on user interaction with the software over a network. If you modify heyform/heyform and deploy it internally for employees only, obligations may differ from public-facing deployments. Consult legal counsel for your specific scenario — this is guidance, not legal advice.

Performance Monitoring: The analytics package tracks completion rates but not server-side latency. Add application performance monitoring (APM) to the Node.js server for bottleneck identification under load. [INTERNAL_LINK: nodejs-performance-monitoring]

Comparison with Alternatives

Feature	heyform/heyform	Typeform	Formbricks
License	AGPL-3.0	Proprietary	AGPL-3.0
Self-hosting	Full support	No	Full support
Conditional logic	Yes	Yes	Yes
Custom CSS	Yes	Limited	Yes
Open source	Full stack	No	Full stack
Primary language	TypeScript	Closed	TypeScript

Typeform dominates the hosted conversational form market but offers no self-hosting and charges per response at scale. Choose heyform/heyform when data control or cost predictability matters more than managed infrastructure.

Formbricks is the closest open-source competitor, also AGPL-3.0 and TypeScript-based. heyform/heyform's smaller contributor base (evident from fork/star ratios) may mean slower feature development, but its focused scope — forms rather than broader experience management — yields simpler deployment. Formbricks targets product analytics integration more aggressively; heyform/heyform emphasizes embeddability and visual customization.

FAQ

What license is heyform/heyform under? GNU Affero General Public License v3.0 (AGPL-3.0). Network use triggers source disclosure obligations.

Can I use heyform/heyform without self-hosting? Yes — the hosted service at my.heyform.net provides managed infrastructure with automatic backups and security updates.

What database does the server require? The README does not specify. Check the local development docs or server package configuration.

Is there an API for programmatic form creation? The README does not document a public API. The server package likely exposes internal endpoints; inspect the source or documentation for details.

How active is development? Last commit was July 14, 2026 per repo stats. The README commits to "regular updates, including bug fixes, new features, and performance improvements."

Can I contribute to the project? Yes — contribution guidelines are at docs.heyform.net/open-source/contribute. The Discord server and GitHub issues are support channels.

What's the minimum Node.js version? Not specified in the README. Consult the local development documentation for current requirements.

Conclusion

heyform/heyform occupies a specific niche: developers and small teams needing conversational, logic-driven forms with full data control. Its TypeScript monorepo architecture supports both complete platform deployment and selective component reuse. The AGPL-3.0 license demands careful evaluation for commercial use cases, but aligns with transparency values in public sector and open-data projects.

The tool is best suited for teams with DevOps^{↗ Bright Coding Blog} capacity to manage self-hosted infrastructure, or those willing to trade customization depth for the convenience of the managed cloud offering. It is less appropriate for teams needing extensive third-party integrations beyond the documented webhook/Zapier/Make.com support, or those requiring a battle-tested enterprise support tier.

If conditional logic, custom CSS, and data sovereignty are priorities, heyform/heyform warrants evaluation. Start with the GitHub repository to inspect the source, then deploy via your preferred path — one-click platform, local development, or the hosted cloud service.