@vulform/astro
Version:
Astro components for VulForm contact form management
293 lines (235 loc) • 7.42 kB
Markdown
# @vulform/astro
Astro components for VulForm contact form management with server-side rendering and progressive enhancement.
## Installation
```bash
npm install @vulform/astro
# or
yarn add @vulform/astro
# or
pnpm add @vulform/astro
# or
bun add @vulform/astro
```
## Setup
### 1. Add the Integration
Add the VulForm integration to your `astro.config.mjs`:
```js
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:
```env
VULFORM_API_KEY=your_api_key_here
```
## Usage
### Basic Usage
```astro
import { VulForm } from '@vulform/astro';
<VulForm
templateId="your-template-id"
apiKey={process.env.VULFORM_API_KEY}
/>
```
### Advanced Usage
```astro
import { VulForm } from '@vulform/astro';
const formConfig = {
templateId: "your-template-id",
apiKey: process.env.VULFORM_API_KEY,
theme: "auto",
prefill: {
name: "John Doe",
email: "john@example.com"
},
enableAnalytics: true,
spamProtection: true,
loadingState: "skeleton",
resetOnSuccess: true,
showSuccessMessage: true
};
<VulForm
{...formConfig}
class="max-w-2xl"
style={{ backgroundColor: '#f9fafb' }}
/>
```
### Custom Styling
```astro
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)
```astro
// 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)
```astro
// 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:
1. **Server-rendered HTML**: Form renders immediately with proper semantic HTML
2. **No-JS fallback**: Form works without JavaScript using standard HTML forms
3. **Client-side enhancement**: JavaScript adds validation, analytics, and better UX
4. **Graceful loading**: Shows appropriate loading states while initializing
## Examples
### Contact Form
```astro
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
```astro
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:
```astro
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](https://vulform.dev)