Forms

Forms lets you publish contact forms, sign-ups and applications without building a page for each one. Staff build a form in the admin area, or you define it in code. Every submission is stored, emailed or passed to your own code. Use it when visitors or users should send you structured answers. For settings a user keeps on their own account, use Preferences instead.

The package is @frigear-nu/forms. Each form is a definition stored in the database.

What you get

• Pages (opt-in): a public page per form at /forms/:slug. <FormRenderer> and a Markdown embed place a form on any other page.
• Admin area (opt-in, with Admin): the form list at /admin/forms, a visual builder for each form, and its submissions.
• Server routes (on by default): read and submit a published form, and a staff API for forms, submissions and access. The staff API is guarded by the forms:manage and forms:credentialspermissions, which the admin role holds.
• Composables and helpers (on by default): defineForm() to write a form in code, and a hook that receives every submission.
• MCP tools (opt-in): list and submit forms, and manage them as staff, through MCP.
• Emails (opt-in per form): each submission is emailed through Notify to the recipients the form names. Your app picks the Notify driver; until it does, emails are not sent.

Quick setup

pnpm add @frigear-nu/forms @nuxthub/core

export default defineNuxtConfig({
  modules: ['@nuxthub/core', '@frigear-nu/forms'],
  forms: {
    settings: {
      pages: { form: true, admin: true, adminForm: true, adminSubmissions: true, adminSubmission: true },
    },
  },
})

pnpm db:generate

export default defineNuxtConfig({
  authorization: {
    roles: {
      manager: { label: 'Coordinator', grant: ['forms:*', 'users:read', 'users:list'], inherit: ['user'] },
    },
  },
})

Options

Options go under the forms key.

settings.pages.* paths keep the parameters of the default, such as :slug. Admin pages need Admin.

settings.rateLimit also caps wrong password attempts, on a separate counter with the same window. 0 turns both off.

captcha.<provider> is turnstile, recaptcha or hcaptcha.

encryptionKey falls back to NUXT_ENCRYPTION_KEY, then to the session password.

Runtime config

Permissions

Forms registers these permissions with Authorization. A staff route calls authorize(event, 'forms:manage').

• Scope: forms (label "Submit forms") expands to forms:submit. A token or OAuth client with it can submit as the user, and nothing else.
• Roles, requirements and policies: the module ships none. The admin role receives the staff permissions through the module's default grants. If you replace the admin role with replace: true, grant them again yourself.
• Why forms:credentials is separate: minting or removing a way into a form is a credential change, so it is session only. A role that grants forms:manage by name must grant forms:credentials too.

See roles and requirements for how roles are built and merged.

Module pages

Next steps

• Build a form – define a contact form in code, seed it and receive it by email.
• Definition – add steps, conditional fields, uploads and an open period.
• Send an email – pick the Notify driver that delivers form emails.