Reference

Entrypoints and builds

Choose between ESM, CommonJS, the browser registry module, and the standalone global IIFE.

The package exposes separate surfaces for module consumers and script-tag consumers. Choose one primary surface per integration.

Decision table

Use caseImportGlobal side effectFormatter behavior
ESM or TypeScript appimport { form } from '@samline/forms'NoneOptional peer must be installed for formatting.
CommonJS appconst { form } = require('@samline/forms')NoneOptional peer must be installed for formatting.
Registry moduleimport * as Forms from '@samline/forms/browser'Installs globalThis.Forms.Optional peer must be installed for formatting.
Registry CommonJSconst Forms = require('@samline/forms/browser')Installs globalThis.Forms.Optional peer must be installed for formatting.
No bundler / CDNLoad dist/browser/forms.global.jsInstalls window.Forms.Formatter is bundled.

Root entrypoint

import { form, browser, parseFormData, validateValues } from '@samline/forms'

The root has no global side effect. browser is the shared registry object, but importing it from the root does not assign window.Forms.

const { form } = require('@samline/forms')

const contact = form('contact-form')

Browser registry module

The /browser subpath exports a default registry and named values, and installs that registry on globalThis.Forms:

import Forms, { available, destroyForm, form, newForm } from '@samline/forms/browser'

const contact = newForm({ id: 'contact-form' })
console.log(available['contact-form'] === contact) // true
destroyForm('contact-form')

Type exports from this subpath are FormsApi, FormsAvailable, and NewFormInput. They are also exported from the package root.

Standalone IIFE

<script src="https://cdn.jsdelivr.net/npm/@samline/forms@3.0.0/dist/browser/forms.global.js"></script>
<script>
  const contact = window.Forms.newForm({ id: 'contact-form' })
</script>

The IIFE is self-contained and cannot be tree-shaken. Pin its version, load it before consumer code, and self-host it when your Content Security Policy does not allow the CDN.

Registry lifecycle

  • newForm({ id, options }) destroys an existing controller under the same id before replacing it.
  • A missing id logs an error and returns undefined.
  • destroyForm(id) destroys and removes an existing entry; missing entries produce a warning.
  • Every spread of the root browser object shares the same closed-over available map.
  • For independent registries, call form() and store controllers in your own Map.