{"id":29708435,"url":"https://github.com/august/astro-phantom-forms","last_synced_at":"2026-03-10T09:39:24.115Z","repository":{"id":299112981,"uuid":"1002074751","full_name":"august/astro-phantom-forms","owner":"august","description":"A spooky little Astro library that makes your forms invisible to bots. No CAPTCHAs. No honeypots. Just pure, elegant ghostery.","archived":false,"fork":false,"pushed_at":"2025-06-17T03:51:11.000Z","size":430,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-01T20:47:29.786Z","etag":null,"topics":["anti-bot","anti-spam","astro","bot-protection","cloaking","forms","hydration","no-captcha","progressive-enhancement","serverless","spam-blocking","stealth","web-components"],"latest_commit_sha":null,"homepage":"","language":"Astro","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/august.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-14T16:56:17.000Z","updated_at":"2025-09-24T12:35:35.000Z","dependencies_parsed_at":"2025-06-14T19:26:48.187Z","dependency_job_id":"e49fc7b5-90d8-43a6-bb70-fcdab3cdac1d","html_url":"https://github.com/august/astro-phantom-forms","commit_stats":null,"previous_names":["august/astro-phantom-forms"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/august/astro-phantom-forms","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/august%2Fastro-phantom-forms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/august%2Fastro-phantom-forms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/august%2Fastro-phantom-forms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/august%2Fastro-phantom-forms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/august","download_url":"https://codeload.github.com/august/astro-phantom-forms/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/august%2Fastro-phantom-forms/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30328873,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T05:25:20.737Z","status":"ssl_error","status_checked_at":"2026-03-10T05:25:17.430Z","response_time":106,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anti-bot","anti-spam","astro","bot-protection","cloaking","forms","hydration","no-captcha","progressive-enhancement","serverless","spam-blocking","stealth","web-components"],"created_at":"2025-07-23T19:01:12.331Z","updated_at":"2026-03-10T09:39:24.045Z","avatar_url":"https://github.com/august.png","language":"Astro","readme":"![Phantom Forms for Astro - Spam Bot Prevention](https://raw.githubusercontent.com/august/astro-phantom-forms/main/phantom.webp)\n\n![npm version](https://img.shields.io/npm/v/astro-phantom-forms)\n\n# 👻 astro-phantom-forms\n\n## Stop spam bots without annoying humans\n### Block form spam with invisible client-side hydration. No CAPTCHAs, no honeypots, no user friction.\n\n![MIT License](https://img.shields.io/badge/license-MIT-green.svg)\n![Built for Astro](https://img.shields.io/badge/astro-forms-orange)\n![Tests](https://img.shields.io/badge/tests-passing-brightgreen)\n![TypeScript](https://img.shields.io/badge/typescript-supported-blue)\n\n\u003e **The Problem**: Spam bots fill out your contact forms, newsletter signups, and comment sections  \n\u003e **The Solution**: Hide forms from server-side rendering, show them only to real users with JavaScript\n\n---\n\n## ⚡ Quick Install\n\n```bash\nnpm install astro-phantom-forms\n```\n\n## 🚀 Quick Start\n\nWrap any form with `PhantomForm` to hide it from bots:\n\n```astro\n---\nimport { PhantomForm } from 'astro-phantom-forms';\n---\n\n\u003cPhantomForm mode=\"visible\"\u003e\n\n  \u003c!-- Your form here --\u003e\n  \u003cform action=\"/contact\" method=\"post\"\u003e\n    \u003cinput type=\"email\" name=\"email\" placeholder=\"your@email.com\" /\u003e\n    \u003ctextarea name=\"message\" placeholder=\"Your message\"\u003e\u003c/textarea\u003e\n    \u003cbutton type=\"submit\"\u003eSend Message\u003c/button\u003e\n  \u003c/form\u003e\n\n\u003c/PhantomForm\u003e\n```\n\n**Result**: Bots see nothing in the HTML source. Real users see the form when they scroll to it.\n\n---\n\n## 🛡️ How It Stops Spam\n\n### Traditional Spam Protection (Annoying)\n- ❌ **CAPTCHAs**: \"Click all the traffic lights\" \n- ❌ **Honeypot fields**: Extra hidden form fields\n- ❌ **Rate limiting**: Block legitimate users too\n- ❌ **JavaScript challenges**: Complex bot detection\n\n### Phantom Forms (Invisible)\n- ✅ **Zero SSR output**: Forms don't exist in HTML source\n- ✅ **Client-only rendering**: JavaScript required to see forms\n- ✅ **Progressive enhancement**: Works with any framework\n- ✅ **Zero user friction**: Humans never know it's there\n\n**The secret**: Most spam bots don't execute JavaScript. They scrape HTML and find... nothing.\n\n---\n\n## 🎯 Use Cases\n\n### Contact Forms\nStop contact form spam without user verification:\n\n```astro\n\u003cPhantomForm mode=\"visible\"\u003e\n  \u003cform action=\"/api/contact\" method=\"post\"\u003e\n    \u003cinput type=\"text\" name=\"name\" required /\u003e\n    \u003cinput type=\"email\" name=\"email\" required /\u003e\n    \u003ctextarea name=\"message\" required\u003e\u003c/textarea\u003e\n    \u003cbutton type=\"submit\"\u003eSend Message\u003c/button\u003e\n  \u003c/form\u003e\n\u003c/PhantomForm\u003e\n```\n\n### Newsletter Signups\nPrevent fake email submissions:\n\n```astro\n\u003cPhantomForm mode=\"idle\"\u003e\n  \u003cform action=\"/api/newsletter\" method=\"post\"\u003e\n    \u003cinput type=\"email\" name=\"email\" placeholder=\"Enter your email\" /\u003e\n    \u003cbutton type=\"submit\"\u003eSubscribe\u003c/button\u003e\n  \u003c/form\u003e\n\u003c/PhantomForm\u003e\n```\n\n### Login Forms\nProtect authentication endpoints:\n\n```astro\n\u003cPhantomForm mode=\"load\"\u003e\n  \u003cform action=\"/api/login\" method=\"post\"\u003e\n    \u003cinput type=\"email\" name=\"email\" /\u003e\n    \u003cinput type=\"password\" name=\"password\" /\u003e\n    \u003cbutton type=\"submit\"\u003eSign In\u003c/button\u003e\n  \u003c/form\u003e\n\u003c/PhantomForm\u003e\n```\n\n### Comment Systems\nBlock comment spam:\n\n```astro\n\u003cPhantomForm mode=\"visible\"\u003e\n  \u003cform action=\"/api/comments\" method=\"post\"\u003e\n    \u003ctextarea name=\"comment\" placeholder=\"Leave a comment...\"\u003e\u003c/textarea\u003e\n    \u003cbutton type=\"submit\"\u003ePost Comment\u003c/button\u003e\n  \u003c/form\u003e\n\u003c/PhantomForm\u003e\n```\n\n---\n\n## 🔧 Hydration Modes\n\nControl when forms appear to users:\n\n| Mode | When Forms Load | Best For |\n|------|----------------|----------|\n| **`load`** | Immediately when page loads | Critical forms (login, checkout) |\n| **`idle`** | When browser is idle | Secondary forms (newsletter, feedback) |\n| **`visible`** | When scrolled into view | Footer forms, below-fold content |\n\n```astro\n\u003c!-- Load immediately for important forms --\u003e\n\u003cPhantomForm mode=\"load\"\u003e\n  \u003cform\u003e\u003c!-- Login form --\u003e\u003c/form\u003e\n\u003c/PhantomForm\u003e\n\n\u003c!-- Load when user scrolls to it --\u003e\n\u003cPhantomForm mode=\"visible\"\u003e\n  \u003cform\u003e\u003c!-- Contact form --\u003e\u003c/form\u003e\n\u003c/PhantomForm\u003e\n\n\u003c!-- Load during browser idle time --\u003e\n\u003cPhantomForm mode=\"idle\"\u003e\n  \u003cform\u003e\u003c!-- Newsletter signup --\u003e\u003c/form\u003e\n\u003c/PhantomForm\u003e\n```\n\n---\n\n## 📦 Framework Support\n\nWorks with all Astro-supported frameworks:\n\n### React Components\n```astro\n---\nimport { PhantomForm } from 'astro-phantom-forms';\nimport ContactForm from '../components/ContactForm.jsx';\n---\n\n\u003cPhantomForm mode=\"visible\"\u003e\n  \u003cContactForm client:load /\u003e\n\u003c/PhantomForm\u003e\n```\n\n### Vue Components  \n```astro\n---\nimport { PhantomForm } from 'astro-phantom-forms';\nimport ContactForm from '../components/ContactForm.vue';\n---\n\n\u003cPhantomForm mode=\"visible\"\u003e\n  \u003cContactForm client:load /\u003e\n\u003c/PhantomForm\u003e\n```\n\n### Svelte Components\n```astro\n---\nimport { PhantomForm } from 'astro-phantom-forms';\nimport ContactForm from '../components/ContactForm.svelte';\n---\n\n\u003cPhantomForm mode=\"visible\"\u003e\n  \u003cContactForm client:load /\u003e\n\u003c/PhantomForm\u003e\n```\n\n### Plain HTML Forms\n```astro\n---\nimport { PhantomForm } from 'astro-phantom-forms';\n---\n\n\u003cPhantomForm mode=\"visible\"\u003e\n  \u003cform action=\"/submit\" method=\"post\"\u003e\n    \u003c!-- Any HTML form --\u003e\n  \u003c/form\u003e\n\u003c/PhantomForm\u003e\n```\n\n---\n\n## 🔍 SEO \u0026 Accessibility\n\n### Search Engine Friendly\n- ✅ **No impact on SEO**: Search engines won't see forms anyway\n- ✅ **Progressive enhancement**: Works without JavaScript for indexing\n- ✅ **Semantic HTML**: Forms use proper markup when rendered\n\n### Accessibility Compliant\n- ✅ **Screen reader compatible**: Forms render normally for assistive tech\n- ✅ **Keyboard navigation**: Full keyboard support maintained  \n- ✅ **Focus management**: Tab order preserved\n- ✅ **ARIA attributes**: All accessibility features intact\n\n### Performance Optimized\n- ✅ **Zero bundle size**: Uses native Web Components\n- ✅ **Lazy loading**: Forms load only when needed\n- ✅ **No dependencies**: Pure JavaScript implementation\n\n---\n\n## 🛠️ Advanced Usage\n\n### Multiple Forms Per Page\n```astro\n\u003c!-- Different hydration for different forms --\u003e\n\u003cPhantomForm mode=\"load\"\u003e\n  \u003cform\u003e\u003c!-- Important form loads immediately --\u003e\u003c/form\u003e\n\u003c/PhantomForm\u003e\n\n\u003cPhantomForm mode=\"visible\"\u003e  \n  \u003cform\u003e\u003c!-- Secondary form loads when visible --\u003e\u003c/form\u003e\n\u003c/PhantomForm\u003e\n\n\u003cPhantomForm mode=\"idle\"\u003e\n  \u003cform\u003e\u003c!-- Background form loads when idle --\u003e\u003c/form\u003e\n\u003c/PhantomForm\u003e\n```\n\n### Direct Component Import\n```astro\n---\nimport PhantomForm from 'astro-phantom-forms/components/PhantomForm.astro';\n---\n\n\u003cPhantomForm mode=\"visible\"\u003e\n  \u003cform\u003e\u003c!-- Your form --\u003e\u003c/form\u003e\n\u003c/PhantomForm\u003e\n```\n\n### TypeScript Support\nFull TypeScript definitions included:\n\n```typescript\ninterface Props {\n  mode?: 'load' | 'idle' | 'visible';\n}\n```\n\n---\n\n## 🧪 Testing \u0026 Development\n\n```bash\n# Run tests\nnpm test\n\n# Build package  \nnpm run build\n\n# Local development\nnpm link\n```\n\n### Verify Spam Protection\nCheck that forms are hidden from SSR:\n\n```bash\n# View source - should show no form elements\ncurl -s https://yoursite.com/contact | grep -i \"\u003cform\"\n\n# Should return empty result\n```\n\n---\n\n## 🔧 Installation \u0026 Setup\n\n### Requirements\n- **Astro** 5.8.1 or higher\n- **Node.js** 18+ \n- **Modern browsers** with JavaScript enabled\n\n### Installation\n```bash\nnpm install astro-phantom-forms\n```\n\n### Import Options\n```astro\n\u003c!-- Named import (recommended) --\u003e\nimport { PhantomForm } from 'astro-phantom-forms';\n\n\u003c!-- Direct import --\u003e\nimport PhantomForm from 'astro-phantom-forms/components/PhantomForm.astro';\n```\n\n---\n\n## 📊 Comparison\n\n| Solution | User Friction | Spam Blocking | SEO Impact | Setup Complexity |\n|----------|---------------|---------------|------------|------------------|\n| **PhantomForm** | ✅ None | ✅ Excellent | ✅ None | ✅ Minimal |\n| CAPTCHA | ❌ High | ✅ Good | ❌ Negative | ❌ Complex |\n| Honeypots | ✅ None | ⚠️ Moderate | ✅ None | ⚠️ Moderate |\n| Rate Limiting | ⚠️ Some | ⚠️ Moderate | ✅ None | ❌ Complex |\n| JS Challenges | ⚠️ Some | ✅ Good | ⚠️ Some | ❌ Complex |\n\n---\n\n## 💡 Why This Works\n\n### The Bot Problem\nMost spam bots:\n- 🤖 Scrape HTML without executing JavaScript\n- 🤖 Submit forms found in static HTML source\n- 🤖 Don't handle client-side rendering\n- 🤖 Target server-side rendered content\n\n### The Phantom Solution  \nPhantomForm:\n- 👻 Hides forms from static HTML (bots see nothing)\n- 👻 Renders forms client-side (humans see everything)\n- 👻 Uses Web Components (native browser support)\n- 👻 Leverages Astro's islands architecture\n\n**Result**: 90%+ spam reduction with zero user impact.\n\n---\n\n## 🚀 Migration Guide\n\n### From Honeypots\n```astro\n\u003c!-- Before: Honeypot field --\u003e\n\u003cform\u003e\n  \u003cinput type=\"text\" name=\"website\" style=\"display:none\" /\u003e\n  \u003cinput type=\"email\" name=\"email\" /\u003e\n  \u003cbutton type=\"submit\"\u003eSubmit\u003c/button\u003e\n\u003c/form\u003e\n\n\u003c!-- After: PhantomForm --\u003e\n\u003cPhantomForm mode=\"visible\"\u003e\n  \u003cform\u003e\n    \u003cinput type=\"email\" name=\"email\" /\u003e\n    \u003cbutton type=\"submit\"\u003eSubmit\u003c/button\u003e\n  \u003c/form\u003e\n\u003c/PhantomForm\u003e\n```\n\n### From CAPTCHA\n```astro\n\u003c!-- Before: CAPTCHA verification --\u003e\n\u003cform\u003e\n  \u003cinput type=\"email\" name=\"email\" /\u003e\n  \u003cdiv class=\"captcha\"\u003e\n    \u003c!-- Complex CAPTCHA widget --\u003e\n  \u003c/div\u003e\n  \u003cbutton type=\"submit\"\u003eSubmit\u003c/button\u003e\n\u003c/form\u003e\n\n\u003c!-- After: PhantomForm --\u003e\n\u003cPhantomForm mode=\"visible\"\u003e\n  \u003cform\u003e\n    \u003cinput type=\"email\" name=\"email\" /\u003e\n    \u003cbutton type=\"submit\"\u003eSubmit\u003c/button\u003e\n  \u003c/form\u003e\n\u003c/PhantomForm\u003e\n```\n\n---\n\n## 🎯 Keywords \u0026 Features\n\n**Spam Protection**: Block form spam, prevent bot submissions, stop automated attacks  \n**Astro Components**: Form components, client-side rendering, islands architecture  \n**Anti-Bot**: Bot detection, spam prevention, automated protection  \n**Web Forms**: Contact forms, newsletter signups, authentication forms  \n**JavaScript**: Client-side hydration, progressive enhancement, Web Components  \n**User Experience**: No CAPTCHAs, frictionless forms, invisible protection  \n\n---\n\n## 📚 More Resources\n\n- 📖 **[Installation Guide](./INSTALLATION.md)** - Detailed setup instructions\n- 🔧 **[Examples](./EXAMPLES.md)** - Real-world usage examples  \n- 🐛 **[Troubleshooting](./TROUBLESHOOTING.md)** - Common issues and solutions\n- 🤝 **[Contributing](./CONTRIBUTING.md)** - Help improve the project\n\n---\n\n## 🙋‍♀️ Support\n\n- 🐛 **Bug reports**: [GitHub Issues](https://github.com/yourusername/astro-phantom-forms/issues)\n- 💬 **Questions**: [GitHub Discussions](https://github.com/yourusername/astro-phantom-forms/discussions)  \n- 📧 **Security issues**: [Contact privately](mailto:security@yoursite.com)\n\n---\n\n## 📄 License\n\nMIT License - see [LICENSE.md](./LICENSE.md) for details.\n\n---\n\n**Stop fighting spam. Start using stealth.** 👻\n\nBuilt with ❤️ for the Astro community.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faugust%2Fastro-phantom-forms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faugust%2Fastro-phantom-forms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faugust%2Fastro-phantom-forms/lists"}