JavaScript SDK

@formerie/client is the public JavaScript and TypeScript helper package for Formerie. It builds runtime URLs, fetches public schemas, submits payloads, normalizes validation errors, and provides browser form helpers. The Formerie runtime API remains the source of truth.

Packages

Framework packages are thin adapters over @formerie/client. They do not duplicate request routing, response parsing, validation error handling, or API security behavior.

Install

npm install @formerie/client

pnpm add @formerie/client

yarn add @formerie/client

bun add @formerie/client

Browser CDN

For plain HTML or browser JavaScript, load the official browser bundle from an immutable Formerie CDN version:

<script src="https://cdn.formerie.com/client/v0.1.0-alpha.6/formerie.iife.js"></script>

Production pages should stay on immutable versioned paths. The /client/latest/ alias is a moving convenience alias for demos and manual testing, not a stable production pin.

Basic Usage

import {
  FormerieRuntimeClient,
  getFieldErrors,
  getFirstFieldError,
  isValidationError
} from "@formerie/client";

const client = new FormerieRuntimeClient();

const result = await client.submit("example.com", "contact", {
  fields: {
    contact: {
      name: "Jane Example",
      email: "jane@example.com"
    }
  },
  verificationToken: captchaToken
});

if (!result.ok && isValidationError(result)) {
  const allEmailErrors = getFieldErrors(result, "contact.email");
  const firstEmailError = getFirstFieldError(result, "contact.email");
}

FormerieRuntimeClient defaults to https://forms.formerie.com and uses clean runtime routes such as /example/contact/submit.

Public Schema Helpers

import {
  evaluatePublicFieldVisibility,
  listPublicSchemaFields
} from "@formerie/client";

const schema = await client.schema("example.com", "contact");

if (schema.ok) {
  const fields = listPublicSchemaFields(schema);
  const visibility = evaluatePublicFieldVisibility(schema, {
    contact: {
      preferredMethod: "email"
    }
  });
}

Schema helpers are for custom rendering and responsive UX. The runtime API still enforces visibility, validation, spam protection, routing, and delivery server-side.

Browser Mount Helpers

import {
  FormerieRuntimeClient,
  mountFormerieRuntimeForm
} from "@formerie/client";

await mountFormerieRuntimeForm("#contact-form", {
  client: new FormerieRuntimeClient(),
  target: {
    workspace: "example.com",
    form: "contact"
  },
  resetOnSuccess: true
});

Use mountFormerieRuntimeForm() when the SDK should load the public schema, render the form, preserve public steps and object groups as fieldsets, render browser-safe verification hooks, load the public verification provider script, and collect verification tokens from those hooks. Use mountFormerieForm() when your app already has a public schema, bindFormerieForm() when your page already rendered a native <form data-formerie-form> shell, and bindFormerieHostedForm() when a server-rendered page already has both a form shell and a public schema JSON script. Generated hosted shells can call mountFormerieForm() with the same public schema plus a backend-owned submitUrl. Pass an explicit verificationToken provider only for custom UIs that do not expose the standard Formerie verification attributes and response fields.

Generated form shells accept public render options for heading output, CSS class hooks, and an optional honeypot field when your server is configured to check one.

These helpers improve browser UX, collect verification tokens, shape payloads, and display validation errors. Final validation, verification, spam checks, submission acceptance, routing, and delivery stay server-side.

Runtime Hostnames

const client = new FormerieRuntimeClient({
  endpoint: "https://forms.example.com"
});

await client.submitWorkspace("contact", {
  fields,
  verificationToken: captchaToken
});

For a hostname bound directly to one form:

const contact = new FormerieRuntimeClient({
  endpoint: "https://contact.example.com"
});

await contact.submitForm({
  fields,
  verificationToken: captchaToken
});