@vulform/js

🚀 Built with Bun for maximum performance!

A powerful, type-safe JavaScript SDK for integrating VulForm contact forms into any web application. Optimized for modern JavaScript runtimes and bundlers.

Features

• ✅ Type-safe - Full TypeScript support with comprehensive types
• ✅ Lightweight - Small bundle size with zero dependencies
• ✅ Robust - Built-in retries, rate limiting, and error handling
• ✅ Real-time validation - Validate fields as users type
• ✅ Analytics - Track form interactions and performance
• ✅ Form enhancement - Automatically enhance existing HTML forms
• ✅ Spam protection - Client-side spam detection
• ✅ Flexible - Works with any JavaScript framework or vanilla JS

⚡️ Quick Start (Bun - Recommended)

# Install with Bun (recommended)
bun add @vulform/js

# Or with other package managers
npm install @vulform/js
pnpm add @vulform/js
yarn add @vulform/js

🎯 Basic Usage

import { VulForm } from '@vulform/js';

// Initialize with your API key
const vulform = new VulForm({
  apiKey: 'vf_your_api_key_here',
  debug: true, // Enable for development
});

// Submit form data
const response = await vulform.submit({
  name: 'John Doe',
  email: '[email protected]',
  message: 'Hello from VulForm!',
});

console.log('Form submitted!', response);

🔧 Auto Form Enhancement

import { VulForm } from '@vulform/js';

const vulform = new VulForm({
  apiKey: 'vf_your_api_key_here',
});

// Automatically enhance any form
const form = document.getElementById('contact-form');
const handler = vulform.setupForm(form);

// The form now has:
// ✅ Automatic submission handling
// ✅ Real-time validation
// ✅ Loading states
// ✅ Error handling
// ✅ Analytics tracking

🏗️ Development with Bun

# Create a new project with Bun
bun create vanilla my-@vulform/app
cd my-@vulform/app

# Add VulForm
bun add @vulform/js

# Start development server
bun run dev

📦 CDN Usage

Via unpkg.com:

<script src="https://unpkg.com/@vulform/js@latest/dist/index.js"></script>
<script>
  const vulform = new Vulform.VulForm({
    apiKey: 'vf_your_api_key_here',
  });
</script>

Via jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/@vulform/js@latest/dist/index.js"></script>
<script>
  const vulform = new Vulform.VulForm({
    apiKey: 'vf_your_api_key_here',
  });
</script>

📦 Bundle Size

Optimized with Bun's bundler:

• Minified: ~8KB gzipped
• Tree-shakeable: Only import what you need
• Zero dependencies: Self-contained

🔥 Advanced Features

Real-time Validation

// Validate individual fields
const emailError = await vulform.validateField('email', 'invalid-email');
if (emailError) {
  console.log('Email error:', emailError.message);
}

// Validate entire form
const validation = vulform.validate({
  email: '[email protected]',
  message: 'Hello!',
});

if (!validation.valid) {
  console.log('Validation errors:', validation.errors);
}

Analytics & Tracking

const vulform = new VulForm({
  apiKey: 'vf_your_api_key_here',
  onSuccess: response => {
    // Track successful submissions
    console.log('Form submitted successfully!', response);
  },
  onError: error => {
    // Handle errors gracefully
    console.error('Submission failed:', error);
  },
  onRateLimit: retryAfter => {
    // Handle rate limiting
    console.log(`Rate limited. Retry after ${retryAfter} seconds`);
  },
});

Custom Configuration

const vulform = new VulForm({
  apiKey: 'vf_your_api_key_here',
  baseUrl: 'https://your-custom-domain.com', // Self-hosted
  timeout: 15000, // 15 second timeout
  retries: 5, // Retry failed requests
  debug: process.env.NODE_ENV === 'development',
});

🌐 CDN Usage (Bun-built)

<!-- Load from CDN (built with Bun) -->
<script
  src="https://vulform.dev/api/sdk/latest"
  integrity="sha384-[hash]"
  crossorigin="anonymous"
></script>

<script>
  const vulform = new Vulform.VulForm({
    apiKey: 'vf_your_api_key_here',
  });
</script>

🔧 Build & Development

This package is built with Bun for optimal performance:

# Install dependencies
bun install

# Build for production
bun run build

# Run tests
bun test

# Type checking
bun run typecheck

# Lint code
bun run lint

🚀 Performance Benefits

Why Bun?

• ⚡️ 3x faster installs than npm
• 🏗️ Built-in bundler with tree-shaking
• 🔥 Native TypeScript support
• 📦 Smaller bundle sizes
• 🛠️ Better developer experience

📚 TypeScript Support

Full TypeScript support out of the box:

import { VulForm, type VulFormConfig, type SubmissionResponse } from '@vulform/js';

const config: VulFormConfig = {
  apiKey: 'vf_your_api_key_here',
  timeout: 10000,
  retries: 3,
};

const vulform = new VulForm(config);

// Type-safe form submission
const response: SubmissionResponse = await vulform.submit({
  name: 'John Doe',
  email: '[email protected]',
  message: 'Hello!',
});

🔗 Related Packages

• @vulform/react - React components
• @vulform/vue - Vue.js components
• @vulform/core - Core utilities (auto-installed)

📄 License

MIT License - see LICENSE for details.

Built with ❤️ and Bun by Dogu Yilmaz