Forminit-js SDK

Forminit

A Framework-agnostic TypeScript SDK for the Forminit form backend, with support for both client-side and server-side usage, including Next.js and Nuxt.js integrations.

Features

• 🌐 Works in both browser and Node.js environments
• 📊 Automatic UTM parameter tracking in browser
• 🔒 Server-side API key authentication
• ⚡ Framework-specific adapters for Next.js and Nuxt.js
• 📝 TypeScript support out of the box
• 🚀 Nuxt.js integration with automatic JSON & FormData parsing

Installation

# Install the core SDK
npm install forminit

Usage

HTML Usage

<form id="contactForm">
  <input type="text" name="fi-sender-firstName" placeholder="First Name" required />
  <input type="text" name="fi-sender-lastName" placeholder="Last Name" required />
  <input type="email" name="fi-sender-email" placeholder="Email" required />
  <textarea name="fi-text-message" placeholder="Message" required></textarea>
  <button type="submit">Send</button>
</form>

<!-- Forminit SDK -->
<script src="https://forminit.com/sdk/v1/forminit.js"></script>
<script>
  const forminit = new Forminit();
  const form = document.getElementById('contactForm');

  form.addEventListener('submit', async (e) => {
    e.preventDefault();
    
    const formData = new FormData(form);
    const { data, redirectUrl, error } = await forminit.submit('YOUR_FORM_ID', formData);

    if (error) {
      console.error('Error:', error.message);
    } else {
      console.log('Success!', data.submissionId);
      form.reset();
    }
  });
</script>

Node Usage

import { Forminit } from 'forminit';

const forminit = new Forminit({
  apiKey: 'your-api-key',
});

// Method 1: Submit using FormData
const formData = new FormData();
formData.append('name', 'John Doe');
formData.append('email', '[email protected]');
const { data, redirectUrl, error } = await forminit.submit('your-form-id', formData);

// Method 2: Submit using object notation
const { data, redirectUrl, error } = await forminit.submit('your-form-id', {
  blocks: [
    {
      type: 'text',
      name: 'name',
      value: 'John Doe',
    },
    {
      type: 'email',
      name: 'email',
      value: '[email protected]',
    },
  ],
});

Next.js Usage

Create a proxy route to securely handle form submissions:

// app/api/forminit/route.ts
import { createForminitProxy } from 'forminit/next';

const forminit = createForminitProxy({
  apiKey: "your-api-key",
});

export const POST = forminit.POST;

Create a client component for your contact form:

// app/components/contact-form.tsx
'use client';

import { useState } from 'react';
import { Forminit } from 'forminit';

export function ContactForm() {
  const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');
  const forminit = new Forminit({ proxyUrl: '/api/forminit' });

  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();
    setStatus('loading');

    const formData = new FormData(e.currentTarget);
    const { error } = await forminit.submit('YOUR_FORM_ID', formData);

    if (error) {
      setStatus('error');
    } else {
      setStatus('success');
      e.currentTarget.reset();
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input type="text" name="fi-sender-fullName" placeholder="Name" required />
      <input type="email" name="fi-sender-email" placeholder="Email" required />
      <textarea name="fi-text-message" placeholder="Message" required />
      <button type="submit" disabled={status === 'loading'}>
        {status === 'loading' ? 'Sending...' : 'Send'}
      </button>
      {status === 'success' && <p>Message sent!</p>}
      {status === 'error' && <p>Something went wrong.</p>}
    </form>
  );
}

Nuxt.js Integration

Option 1: Built-in Body Parsing (Recommended)

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    forminitApiKey: "your-api-key",
  },
});

// server/api/forminit.post.ts
import { createForminitNuxtHandler } from 'forminit/nuxt';

export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig();

  const forminitHandler = createForminitNuxtHandler({
    apiKey: config.forminitApiKey,
  });

  return await forminitHandler(event);
});

Option 2: Manual Setup

// server/api/forminit.post.ts
import { createForminitNuxtHandler } from 'forminit/nuxt';

const config = useRuntimeConfig();

const forminitHandler = createForminitNuxtHandler({
  apiKey: config.forminitApiKey,
});

export default defineEventHandler(forminitHandler);

Configuration

The Forminit constructor accepts the following options:

interface ForminitConfig {
  apiKey?: string; // Required for server-side usage
  proxyUrl?: string; // Optional and only for client-side usage with proxy
}

Type Definitions

The SDK includes TypeScript definitions for all its interfaces:

interface FormBlock {
  type: string;
  name?: string;
  value?: string | number | boolean;
  properties?: Record<string, unknown>;
}

interface FormResponse {
  success: boolean;
  submissionId?: string;
  error?: string;
}

Example Usage with Different Block Types

const response = await forminit.submit('your-form-id', {
  blocks: [
    {
      type: 'sender',
      properties: {
        email: '[email protected]',
        firstName: 'John',
        lastName: 'Doe',
        phone: '+442071234567',
        company: 'Acme Corp',
      },
    },
    {
      type: 'text',
      name: 'message',
      value: 'Hello, I would like to learn more about your services.',
    },
  ],
});

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT