@formgong/core

@formgong/core

A tiny, typed client for Formgong, the form backend for contact forms. Post a form from any JavaScript runtime and the submission arrives by email, Telegram or webhook. You don't need a server, a database or SMTP.

• About 3 kB min+gzip, no dependencies. ESM and CJS builds with TypeScript types.
• Runs anywhere: browsers, Node 18+, Deno, Bun, Cloudflare Workers, Vercel and Netlify Edge.
• Typed errors carry stable codes such as unknown_access_key, rate_limited and turnstile_missing.
• Anti-spam built in: honeypot handling, and the same behaviour signals and proof-of-work as Formgong's fg.js.
• Account API (@formgong/core/api) for scripts and AI agents: list forms, create a form, get a snippet, read submissions.

npm install @formgong/core

Quick start

import { submit, FormgongError } from "@formgong/core";

try {
  const { id, message } = await submit("fk_your_access_key", {
    name: "Ada Lovelace",
    email: "ada@example.com",
    message: "Hello!",
  });
  console.log(message); // "Sent. Thank you!" (localized)
} catch (error) {
  if (error instanceof FormgongError) console.error(error.code, error.message);
}

Get a free access key (fk_…) at formgong.com. It is public by design: it can only send submissions to your form, so it is safe in frontend code.

Browser forms

import { createTracker, submit } from "@formgong/core";

const form = document.querySelector("form")!;
// Optional: the same anti-spam signals as fg.js (typing/paste counts + a small proof-of-work).
const tracker = createTracker(form, "fk_your_access_key");

form.addEventListener("submit", async (event) => {
  event.preventDefault();
  const result = await submit("fk_your_access_key", form, { tracker, lang: "de" });
  form.reset();
  tracker.next();
  alert(result.message);
});

Add a hidden honeypot field to the form, <input name="botcheck" tabindex="-1" autocomplete="off" style="position:absolute;left:-10000px">, and keep it empty.

API

submit(accessKey, data, options?) => Promise<SubmitResult>

data can be a plain object, FormData, URLSearchParams or an HTMLFormElement. Objects are sent as JSON, with arrays joined as "a, b". Objects that contain a Blob or File are sent as multipart. FormData is copied, so your object is never modified.

It resolves to { success: true, id, lang, message } and throws FormgongError on failure.

FormgongError

Other helpers:

• trySubmit(): the same as submit but never throws. It returns { ok, result | error }.
• createClient(accessKey, defaults): binds an access key and default options once.
• honeypotTriggered(data): tells you whether a honeypot field is filled in.

Anti-spam: createTracker(target, accessKey, options?)

It counts keydowns, pastes and the distinct fields typed into, starting from when the form is seen. On the first interaction it fetches a signed challenge from GET /pow?k=… and solves it in the background with Web Crypto (SHA-256, about 13 bits, typically a fraction of a second). Call tracker.signals() to get { _fg_b, _fg_pow }. It waits up to 2 s for the proof-of-work, like fg.js.

Formgong only scores these signals when _fg_b is present. Server-side and SDK posts without them are never penalised, so never create a tracker on a server and never fake the values.

Lower-level helpers: solvePow(challenge), fetchPowChallenge(accessKey), leadingZeroBits().

Account API: @formgong/core/api

import { FormgongApi } from "@formgong/core/api";

const api = new FormgongApi({ token: process.env.FORMGONG_TOKEN }); // fgp_… personal API token
const { form } = await api.createForm({ name: "Contact – acme.com" });
const { code } = await api.getFormSnippet({ form_id: form.id, framework: "react" });
const { submissions } = await api.listRecentSubmissions({ form_id: form.id, limit: 5 });

This talks JSON-RPC to the Formgong MCP endpoint (POST https://formgong.com/mcp). Create tokens under Dashboard → Account → API tokens. Personal tokens are secrets: use them on the server, in scripts or in CI, never in a browser. Limits: 60 requests per minute per token and 10 new forms per hour.

Server-side notes

From a server (Node, Workers, Server Actions), per-IP rate limits apply to your server's IP: 20 submissions per minute per IP and 30 per minute per form. If the form only allows certain domains, pass origin. For Next.js, use @formgong/next, which forwards Origin and Accept-Language for you.

Why Formgong

Formgong is a hosted form backend with a free plan, built for static and AI-built sites. Submissions go to email and Telegram, plus webhooks for Make, n8n and Zapier. Data is stored in the EU, and messages and autoreplies come in 12 languages. Spam filtering includes a honeypot, optional Cloudflare Turnstile and cookie-free behaviour signals, with no stored fingerprints.

How it compares with Formspree, Web3Forms, Basin, Getform, FormSubmit and Netlify Forms: formgong.com/en/compare. Moving from Formspree takes one line: change the form action or the access key (guide).

Packages

Links

• Docs: https://formgong.com/en/docs/
• MCP server for Cursor, Claude and VS Code: https://formgong.com/en/docs/mcp/
• Source: https://github.com/formgong/js
• Issues: https://github.com/formgong/js/issues
• Support: support@formgong.com

License

MIT © Formgong