@vulform/astro
v1.1.0
Published
Astro components for VulForm contact form management
Maintainers
doguyilmazReadme
@vulform/astro
Astro components for VulForm contact form management with server-side rendering and progressive enhancement.
Installation
npm install @vulform/astro
# or
yarn add @vulform/astro
# or
pnpm add @vulform/astro
# or
bun add @vulform/astroSetup
1. Add the Integration
Add the VulForm integration to your astro.config.mjs:
import { defineConfig } from 'astro/config';
import { VulFormIntegration } from '@vulform/astro';
export default defineConfig({
integrations: [
VulFormIntegration({
apiKey: process.env.VULFORM_API_KEY, // Optional: set globally
apiUrl: 'https://api.vulform.dev', // Optional: custom API URL
debug: false, // Optional: enable debug mode
}),
],
});2. Environment Variables
Create a .env file in your project root:
VULFORM_API_KEY=your_api_key_hereUsage
Basic Usage
---
import { VulForm } from '@vulform/astro';
---
<VulForm
templateId="your-template-id"
apiKey={process.env.VULFORM_API_KEY}
/>Advanced Usage
---
import { VulForm } from '@vulform/astro';
const formConfig = {
templateId: "your-template-id",
apiKey: process.env.VULFORM_API_KEY,
theme: "auto",
prefill: {
name: "John Doe",
email: "[email protected]"
},
enableAnalytics: true,
spamProtection: true,
loadingState: "skeleton",
resetOnSuccess: true,
showSuccessMessage: true
};
---
<VulForm
{...formConfig}
class="max-w-2xl"
style={{ backgroundColor: '#f9fafb' }}
/>Custom Styling
---
import { VulForm } from '@vulform/astro';
---
<VulForm
templateId="your-template-id"
class="custom-form-class"
/>
<style>
.custom-form-class {
max-width: 600px;
margin: 0 auto;
padding: 2rem;
background: white;
border-radius: 0.5rem;
box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
}
.custom-form-class :global(.vulform-input) {
border-radius: 0.75rem;
padding: 1rem;
}
.custom-form-class :global(.vulform-submit-button) {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
border: none;
border-radius: 0.75rem;
padding: 1rem 2rem;
font-weight: 600;
text-transform: uppercase;
letter-spacing: 0.05em;
}
</style>Props
| Prop | Type | Default | Description |
| -------------------- | -------------------------------------- | ----------------------------- | -------------------------------------- |
| templateId | string | Required | Your VulForm template ID |
| apiKey | string | process.env.VULFORM_API_KEY | Your VulForm API key |
| apiUrl | string | 'https://api.vulform.dev' | VulForm API URL |
| theme | 'auto' \| 'light' \| 'dark' | 'auto' | Form theme |
| class | string | '' | CSS class for the form container |
| style | object | {} | Inline styles for the form container |
| prefill | object | {} | Pre-fill form fields |
| enableAnalytics | boolean | true | Enable form analytics |
| spamProtection | boolean | true | Enable spam protection |
| loadingState | 'default' \| 'skeleton' \| 'spinner' | 'default' | Loading state style |
| resetOnSuccess | boolean | true | Reset form after successful submission |
| showSuccessMessage | boolean | true | Show success message after submission |
| autoRedirect | boolean | false | Auto-redirect after submission |
Server-Side Rendering (SSR)
VulForm Astro components are designed to work with both static site generation (SSG) and server-side rendering (SSR). The components render a loading state on the server and progressively enhance with JavaScript on the client.
SSG (Static Site Generation)
---
// pages/contact.astro
import { VulForm } from '@vulform/astro';
---
<html>
<head>
<title>Contact Us</title>
</head>
<body>
<main>
<h1>Contact Us</h1>
<VulForm templateId="contact-form" />
</main>
</body>
</html>SSR (Server-Side Rendering)
---
// pages/contact.astro
import { VulForm } from '@vulform/astro';
// Access form data on the server
const formData = Astro.url.searchParams.get('form-data');
---
<html>
<head>
<title>Contact Us</title>
</head>
<body>
<main>
<h1>Contact Us</h1>
<VulForm
templateId="contact-form"
prefill={formData ? JSON.parse(formData) : {}}
/>
</main>
</body>
</html>Progressive Enhancement
The Astro component uses progressive enhancement to provide a great user experience:
- Server-rendered HTML: Form renders immediately with proper semantic HTML
- No-JS fallback: Form works without JavaScript using standard HTML forms
- Client-side enhancement: JavaScript adds validation, analytics, and better UX
- Graceful loading: Shows appropriate loading states while initializing
Examples
Contact Form
---
import { VulForm } from '@vulform/astro';
---
<section class="py-16 bg-gray-50">
<div class="max-w-2xl mx-auto px-4">
<h2 class="text-3xl font-bold text-center mb-8">Get in Touch</h2>
<VulForm
templateId="contact-form"
class="bg-white p-8 rounded-lg shadow-lg"
prefill={{
source: "Website Contact Form"
}}
enableAnalytics={true}
spamProtection={true}
/>
</div>
</section>Newsletter Signup
---
import { VulForm } from '@vulform/astro';
---
<div class="bg-blue-600 text-white py-8">
<div class="max-w-4xl mx-auto px-4">
<div class="text-center mb-6">
<h3 class="text-2xl font-bold">Stay Updated</h3>
<p class="text-blue-100">Get the latest news and updates</p>
</div>
<VulForm
templateId="newsletter-signup"
class="max-w-md mx-auto"
theme="dark"
resetOnSuccess={true}
showSuccessMessage={true}
/>
</div>
</div>TypeScript Support
The package includes full TypeScript support:
---
import type { VulFormProps } from '@vulform/astro';
import { VulForm } from '@vulform/astro';
interface Props {
templateId: string;
title?: string;
}
const { templateId, title = "Contact Form" }: Props = Astro.props;
const formConfig: VulFormProps = {
templateId,
apiKey: process.env.VULFORM_API_KEY!,
theme: 'auto',
enableAnalytics: true,
spamProtection: true,
};
---
<div>
<h2>{title}</h2>
<VulForm {...formConfig} />
</div>License
MIT © VulForm