HeyForm: an AGPL-3.0 form builder you can self-host

What HeyForm actually is, and who the README is written for

HeyForm is an open-source form builder aimed at small businesses, according to its README. The forms it produces are conversational: surveys, quizzes and polls, with input types that go past plain text into picture choices, date pickers and file uploads. Conditional logic and URL redirection let a form branch while the respondent is filling it in.

The README's first recommendation is not self-hosting. It points readers at the official hosted service at my.heyform.net, describing it as the simplest way in and citing automatic backups and maintenance handled by the two maintainers. That ordering is deliberate and worth reading as a design statement: the project is maintained by a small team, and the hosted product is how the work is funded. Self-hosting instructions live on a separate site, docs.heyform.net/open-source/self-hosting, not in the repository README.

So the audience is split. A small business that wants forms without running infrastructure should use the hosted service. An engineer who wants the code on their own server is supported, but is routed to documentation the repository does not reproduce. The repository itself is a pnpm workspace of seven packages, and the top-level entries include a Dockerfile, a docker-compose.test.yml and a scripts directory.

The monorepo layout: server, webapp, renderer and embed

The README's structure block lists seven packages: answer-utils, embed, form-renderer, shared-types-enums, utils, server and webapp. The split matters because it tells you which piece you would touch for a given change.

packages/server is the Node server. packages/webapp is the React application. packages/form-renderer is the library that draws a form, and packages/embed is a JavaScript library for embedding one elsewhere. answer-utils holds form submission utilities shared between server and webapp, while shared-types-enums and utils carry the shared types and helpers that keep the two sides in agreement. That is a conventional arrangement for a product with a builder UI and a public-facing form surface, and it means the rendering path is reusable outside the main webapp.

The Dockerfile confirms how the pieces assemble at build time. It builds the server and the webapp, then copies the webapp's dist/static output into packages/server/static and its dist/index.html into packages/server/view/index.html. In other words, the production image serves the built React app from the Node server rather than running two processes behind a proxy. That is a simpler deployment shape, and it also means the frontend and backend ship as one unit, so you cannot upgrade them independently.

Installing HeyForm locally with pnpm

The root package.json sets the toolchain expectations: pnpm 8 or later and Node 20 or later. The repository is a pnpm workspace, so installs happen at the root and scripts fan out to the packages.

Install dependencies from the repository root:

pnpm install

Then start both the webapp and the server in development mode with the root dev script, which runs dev:webapp and dev:server in parallel via npm-run-all:

pnpm dev

The README does not state which ports the two development processes bind to, and it does not list the environment variables the server needs. For those, it defers to the local installation page at docs.heyform.net/open-source/local-development. Treat that page as required reading before the first run rather than optional background.

For a production build, the root scripts are separate:

pnpm build:server
pnpm build:webapp

The Dockerfile shows the order the project uses: build the server, build the webapp, then copy the webapp output into the server's static and view directories. If you are containerising HeyForm yourself, that sequence is the one to copy.

HeyForm docker: what the Dockerfile does and does not pin down

The Dockerfile is a multi-stage build. It starts from node:22.23.2-alpine3.23 as the base image, installs pnpm 9.15.9 globally, and adds python3, make and g++ so native modules can compile. Those build tools stay in the earlier stages; the comment in the file notes that the final runtime image does not inherit them, which keeps the shipped image smaller.

Dependency fetching is separated from source copying. The fetched stage copies only package.json, pnpm-lock.yaml and pnpm-workspace.yaml and runs pnpm fetch with --frozen-lockfile against a BuildKit cache mount. The build stage then copies the individual package manifests for server, webapp and form-renderer before copying source, so a source-only change reuses the installed dependencies. This is a well-considered cache layout, and it is the strongest engineering signal in the repository.

What the Dockerfile does not contain is a database. There is no service definition, no volume for persistent data beyond a static/upload directory it creates, and no environment block. The README offers one-click deployment templates for Zeabur, Sealos, RepoCloud and Alibaba Cloud ComputeNest, which suggests those platforms supply the surrounding infrastructure. If you are writing your own compose file, the repository's docker-compose.test.yml is the only compose file present, and its name says it is for testing. Check the self-hosting documentation for the database and storage requirements before assuming a single container is enough.

Where HeyForm is the wrong tool

The licence is the first constraint. HeyForm is AGPL-3.0, and the README links to a licence page at docs.heyform.net/open-source/license for compliance details. The AGPL's network clause is the part that catches people: if you modify HeyForm and let users interact with it over a network, the licence's obligations reach that deployment in a way the plain GPL's do not. For an internal survey tool this is usually unremarkable. For a company that wants to take the form builder, extend it, and offer it as part of a closed hosted product, it is a genuine blocker, and no amount of self-hosting changes that.

The second constraint is operational. The README's self-hosting path points off-site, and the repository does not document the environment variables, database or storage backend the server needs. That is not a criticism of the code, but it does mean the first deployment is a documentation-reading exercise rather than a copy-paste. Teams without anyone comfortable debugging a Node server and its data layer will have a worse time than they would with the hosted service.

Third, the upgrade story is thin in the repository. Releases are tagged, with v3.0.3 published on 2026-09-09, v3.0.2 on 2026-08-28 and v3.0.1 on 2026-08-13, so the cadence is roughly every two to three weeks. What the README does not document is rollback, migration steps between versions, or a supported upgrade path for self-hosted instances. If you self-host, back up your database before pulling a new tag, because the project does not tell you how to undo one.

HeyForm compared with Formbricks and Typeform

The two comparisons people search for are Formbricks and Typeform, and they are different kinds of alternative.

Typeform is the commercial product HeyForm's conversational format is modelled on. The difference is not features but control: Typeform is a hosted SaaS with a per-response pricing model, and the README's own framing positions HeyForm's hosted service as the equivalent convenience option. Choosing HeyForm means choosing either to pay the maintainers for hosting or to run the stack yourself. The form-building experience is the comparable part; the deployment model is not.

Formbricks is the closer comparison, because it is also an open-source survey tool you can self-host. The distinction visible in HeyForm's repository is architectural: HeyForm splits a form-renderer package and an embed library out of the main webapp, so the rendering surface is a reusable library rather than only an application screen. If your use case is embedding forms into an existing site, that separation is the thing to evaluate. Formbricks' own architecture is outside the scope of this repository, so compare the two on their respective documentation rather than on the feature lists in either README.

A third option worth naming is simply the hosted HeyForm at my.heyform.net. It is the same codebase, and the README is explicit that choosing it supports development. For a small business, that is often the honest answer.

Maintenance, licence and what to verify before you commit

The repository is not archived, and the last push was on 2026-09-09, which is recent. Releases v3.0.1 through v3.0.3 landed across August and September 2026, so the project is being worked on. The README describes the maintainers as a duo, which is the relevant maintenance fact: this is a small team, not a foundation-backed project, and the hosted service is what funds it. Plan for that level of bus factor.

On licence, the AGPL-3.0 is the whole story and it is not a formality. The README links to docs.heyform.net/open-source/license for how to comply, and that page, not this article, is where the obligations are spelled out. If your organisation has a policy against AGPL dependencies in products it distributes or hosts for customers, HeyForm will trip it. That is a policy question for your legal team, and the practical move is to check the licence page before you invest engineering time in a self-hosted deployment.

Upgrade cost is the open item. Version tags exist, but the README does not describe migrations, schema changes or a rollback procedure. The concrete thing to verify first is how the server stores data and whether a version bump requires a migration step, because that determines whether upgrading is a tag change or a maintenance window.

Editorial conclusion

HeyForm fits teams that want a self-hosted conversational form builder and can accept AGPL-3.0, or that would rather pay for the hosted service at my.heyform.net. It is the wrong choice if you need to embed the form builder inside a closed-source product, or if you want a single container with no external database. Before committing, read the self-hosting page at docs.heyform.net/open-source/self-hosting, confirm which database and storage the server package expects, and decide whether the AGPL-3.0 network clause applies to your deployment.

Frequently asked questions

Official sources

1. heyform/heyform on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases