@vulform/js
Version:
JavaScript SDK for VulForm contact form management
256 lines (192 loc) • 5.51 kB
Markdown
# @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)
```bash
# 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
```javascript
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: 'john@example.com',
message: 'Hello from VulForm!',
});
console.log('Form submitted!', response);
```
## 🔧 Auto Form Enhancement
```javascript
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
```bash
# 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:**
```html
<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:**
```html
<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
```javascript
// 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: 'john@example.com',
message: 'Hello!',
});
if (!validation.valid) {
console.log('Validation errors:', validation.errors);
}
```
### Analytics & Tracking
```javascript
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
```javascript
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)
```html
<!-- 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:
```bash
# 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:
```typescript
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: 'john@example.com',
message: 'Hello!',
});
```
## 🔗 Related Packages
- **[@vulform/react](../@vulform/react)** - React components
- **[@vulform/vue](../@vulform/vue)** - Vue.js components
- **[@vulform/core](../@vulform/core)** - Core utilities (auto-installed)
## 📄 License
MIT License - see [LICENSE](../../LICENSE) for details.
---
**Built with ❤️ and Bun by Dogu Yilmaz**