https://github.com/adityaarsharma/hatch
🐣 Headless WordPress, made easy. WordPress plugin + Astro starter + Claude Code plugin. Free, open source, vendor-neutral. Make WordPress fast and secure — without changing how editors work.
https://github.com/adityaarsharma/hatch
ai-guided astro astro-starter claude-code decoupled-wordpress faust-alternative frontity-alternative headless-cms headless-wordpress jamstack rankmath wordpress wordpress-rest-api wp-rest-api yoast
Last synced: 21 days ago
JSON representation
🐣 Headless WordPress, made easy. WordPress plugin + Astro starter + Claude Code plugin. Free, open source, vendor-neutral. Make WordPress fast and secure — without changing how editors work.
- Host: GitHub
- URL: https://github.com/adityaarsharma/hatch
- Owner: adityaarsharma
- License: mit
- Created: 2026-05-13T05:30:46.000Z (22 days ago)
- Default Branch: main
- Last Pushed: 2026-05-13T06:35:15.000Z (22 days ago)
- Last Synced: 2026-05-13T07:33:53.254Z (22 days ago)
- Topics: ai-guided, astro, astro-starter, claude-code, decoupled-wordpress, faust-alternative, frontity-alternative, headless-cms, headless-wordpress, jamstack, rankmath, wordpress, wordpress-rest-api, wp-rest-api, yoast
- Language: PHP
- Homepage: https://github.com/adityaarsharma/hatch
- Size: 235 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
# 🐣 Hatch — The Headless Engine for WordPress
**One WordPress plugin. Premium admin. Push updates from wp-admin. Ship headless sites without giving up your CMS.**
A free, MIT-licensed engine that turns WordPress into a real headless backend for Astro, Next.js, or anything else that speaks REST. **No external infrastructure. No phone-home. No vendor lock-in.**
[](#install-the-plugin)
[](LICENSE)
[](https://astro.build)
[](https://wordpress.org)
[](https://github.com/adityaarsharma/hatch/releases/latest)
[](CONTRIBUTING.md)
### 📦 [**Download Hatch v0.5.0 →**](https://github.com/adityaarsharma/hatch/releases/latest/download/hatch.zip)
_Drop into `wp-content/plugins/`. Activate. Open Tools → Hatch. Done._
[Why Hatch](#why-hatch-exists) · [What's inside](#whats-inside-the-plugin) · [Install](#install-the-plugin) · [How it works](#how-it-works) · [Hatch vs alternatives](#hatch-vs-the-alternatives) · [FAQ](#faq)
**👋 New to headless WordPress?** Start with the [plain-English explainer →](docs/what-is-headless-wordpress.md) (restaurant analogy + diagrams)
---
## Why Hatch exists
Headless WordPress is a great idea with a terrible developer experience.
**Faust.js** needs WP Engine + WPGraphQL. **Gatsby** is locked to Netlify and dying. **Frontity** died in 2022. **Rolling your own** with REST takes weeks, and the first time RankMath, ACF, or a CPT misbehaves, you're alone.
Hatch is the missing middle. **One WordPress plugin** that:
- Hardens the REST API and detects every gotcha before you hit it
- Auto-bridges your existing plugins (RankMath, Yoast, ACF, Meta Box, WPForms, Fluent, Gravity, CF7, WPML, Polylang, Pods, CPT UI, Redirection — 24+ supported)
- Generates Application Passwords on demand with a `.env` block you can paste straight into your frontend
- Pushes updates to your VPS over an HMAC-signed channel (no SSH password in WordPress)
- Ships 8 headless-first Gutenberg blocks with Tailwind output
- Looks and feels like Linear, not 2014 wp-admin
**No one else is bundling this.** It's the kind of plugin you'd build at 2 a.m. after one too many "why isn't the post showing on the frontend" debugging sessions — except it already exists.
---
## What's inside the plugin
Six tabs. Every screen designed end-to-end.
```
╭─[H]─ Hatch ─────────────────────────────── v0.5.0 · [GitHub] · [Docs] ─╮
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ 🔌 Connection │🔑 Connector │🚀 Frontend │♥ Health │🛡 Sec │🧩 │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
╰─────────────────────────────────────────────────────────────────────────╯
```
### 🔌 Connection
Set your frontend's revalidation webhook URL. Pick which post types fire webhooks (so saving a menu item doesn't trigger a rebuild). Test the connection with one click.
### 🔑 Connector — the showpiece
- **12-point preflight diagnostic**: WP version, PHP version, permalinks, HTTPS, REST API reachable, REST auth working, Application Passwords available, blocking plugins detected, cache plugins flagged, CORS hints, webhook configured, ACF + CPT REST exposure
- **Application Password generator** with one-time plaintext display and copy-ready `.env` block (`HATCH_WP_URL`, `WORDPRESS_USER`, `WORDPRESS_APP_PASSWORD`, `HATCH_WEBHOOK_SECRET`)
- **4 hosting cards** with real 1-click deploy buttons (Cloudflare Workers, Vercel, Netlify, VPS)
### 🚀 Frontend — RunCloud-style update agent
Two paths to push updates from WordPress to your headless frontend:
**Hatch Agent (recommended)** — a tiny Node.js daemon you install on your VPS with one curl command. WordPress sends HMAC-signed POST requests; the agent runs whitelisted commands (`git pull → npm install → npm run build → pm2 reload`) and streams the log back. **No SSH credentials stored in WordPress.**
**SSH (advanced)** — for users who can't install the agent. Credentials encrypted with sodium. Only whitelisted commands run. Never any arbitrary shell access.
### ♥ Health
Live status grid for every check Hatch can verify. Green is good, yellow needs attention, red is broken. Every issue has a direct "Open →" link to the screen that fixes it.
### 🛡 Security
- REST API hardening (anonymous users → 401, `?author=N` blocked, `` REST link tags stripped)
- XML-RPC kill switch
- **Custom login URL** with the WPS Hide Login approach (2M+ install precedent)
- **Headless role guard** — kicks subscribers/customers/members out of wp-admin (they have no reason to be there in a headless setup)
- **Brute-force IP lockout** with hashed-IP transients (no raw IPs stored)
### 🧩 Plugins
Dense, scannable grid of all 24 plugins Hatch tracks. Active status, "Hatch-compatible" hints, instant visual confirmation.
---
## What else is in the plugin
Stuff that doesn't fit in tabs:
### 8 headless-first Gutenberg blocks
**Section · Container · Heading · Paragraph · Button · Image · Hero · Custom Code.** Every block saves static HTML with Tailwind utility classes. **Zero PHP at render time.** Works in any frontend that can render HTML. Includes 5-breakpoint responsive controls, 9 semantic color tokens, gradient presets.
### The Custom Code Block
The "headless shouldn't be boring" answer. Drop in any HTML/CSS/JS with three execution modes:
| Mode | What runs | When to use |
|---|---|---|
| **Inline** (default) | HTML + scoped CSS | Marquees, gradients, neon text, CSS animations |
| **Shadow DOM** | HTML + CSS + JS in a `` Web Component | Interactive widgets you trust |
| **Iframe** | Sandboxed `` | Untrusted third-party embeds |
Plus 8 designer snippets pre-loaded — animated gradient, smooth marquee, glassmorphism card, neon glow, typewriter, scroll parallax, 3D card flip, particle canvas. Click → instantly editable.
### 4-step setup wizard
First-run experience for non-terminal users. Welcome (with diagnostic) → Frontend URL → Application Password → Theme picker (Blog / Tech / Docs). Skippable. Comes back via Tools → Hatch anytime.
### WP-CLI commands
For terminal users — the "skip the wizard" path:
```bash
wp hatch setup --frontend=https://mysite.com # full setup in one command
wp hatch diagnose # 12 checks, exit code 1 on fail
wp hatch generate-token # App Password only
wp hatch info # detection report
wp hatch revalidate # fire webhook
wp hatch env # print .env block
```
### REST API surface
Everything Hatch does is available via `/wp-json/hatch/v1/*`:
```
GET /info site metadata + detection report
GET /seo-head?url=… RankMath OR Yoast getHead proxy
GET /redirects merged from RankMath + Redirection plugin
GET /forms list all forms (WPForms/Fluent/Gravity/CF7)
POST /forms/{id}/submit submit a form
GET /cpt-health CPT REST exposure scan
GET /acf-status ACF/Meta Box field group REST status
POST /revalidate manual webhook fire
GET /diagnostic run the 12-point preflight
POST /app-password generate App Password
POST /agent/* frontend agent control
```
---
## Install the plugin
### 🚀 1-click download
> **[hatch.zip — v0.5.0](https://github.com/adityaarsharma/hatch/releases/latest/download/hatch.zip)**
1. Download the ZIP
2. WordPress admin → **Plugins → Add New → Upload Plugin** → choose `hatch.zip` → **Install Now** → **Activate**
3. Open **Tools → Hatch** — the setup wizard starts automatically
### 🖥 SSH / terminal install
```bash
cd /var/www/your-wp-site/wp-content/plugins
wget https://github.com/adityaarsharma/hatch/releases/latest/download/hatch.zip
unzip hatch.zip && rm hatch.zip
# Activate
wp plugin activate hatch
# OR run full setup from CLI
wp hatch setup --frontend=https://your-headless-site.com
```
### 📦 Composer (for Bedrock / Roots users)
```bash
composer require adityaarsharma/hatch:dev-main
```
### 🛠 From source
```bash
git clone https://github.com/adityaarsharma/hatch.git
cp -r hatch/wp-plugin /path/to/wp-content/plugins/hatch
```
---
## Requirements
- WordPress **6.4+**
- PHP **7.4+** (PHP 8.2+ recommended)
- A headless frontend — Astro, Next.js, SvelteKit, Nuxt, anything that speaks HTTP
- **Strong recommendation:** install WordPress on a **subdomain you control** (e.g. `cms.yoursite.com`), not your root domain. Hatch detects root-domain installs and warns you — but it's much easier to start right than migrate later.
---
## How it works
```mermaid
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#dbeafe","primaryTextColor":"#0f172a","primaryBorderColor":"#2563eb","lineColor":"#64748b","fontSize":"14px"}}}%%
flowchart LR
Editor("✏️ Editor"):::neutral
WordPress["🐣 WordPress + Hatch
━━━━━━━━━━━━━
your-cms.example.com
(not publicly accessible)"]:::backend
REST["REST API
+ App Password"]:::api
Frontend["⚡ Astro frontend
━━━━━━━━━━━━━
example.com
(your visitors)"]:::frontend
Visitor("👤 Visitor"):::neutral
Agent["🤖 Hatch Agent
(on your VPS)"]:::agent
Editor -->|writes posts| WordPress
WordPress -->|exposes content| REST
REST -->|fetched at build/request| Frontend
Frontend -->|serves pages| Visitor
WordPress -.->|HMAC update push| Agent
Agent -.->|git pull + build + reload| Frontend
classDef neutral fill:#f1f5f9,stroke:#cbd5e1,color:#0f172a
classDef backend fill:#fef3c7,stroke:#f59e0b,color:#78350f
classDef api fill:#dbeafe,stroke:#2563eb,color:#1e40af
classDef frontend fill:#d1fae5,stroke:#10b981,color:#065f46
classDef agent fill:#e0e7ff,stroke:#6366f1,color:#3730a3
```
**Three pieces, one plugin, zero proprietary infrastructure:**
1. **Companion features** harden REST and bridge your existing WP plugins. Always-on, no setup.
2. **Setup wizard + Connector** generates the credentials your frontend needs (App Password + webhook secret) and gives you a copy-paste `.env`.
3. **Frontend Agent** lets you push updates to your VPS frontend from WordPress, without storing SSH passwords.
---
## Hatch vs the alternatives
| | **Hatch** | Faust.js | gatsby-source-wordpress | Frontity | DIY |
|---|---|---|---|---|---|
| Works with Astro | ✅ | ❌ Next.js only | Possible (no support) | ❌ | Manual |
| Works without GraphQL | ✅ REST native | ❌ WPGraphQL required | ❌ WPGraphQL required | ✅ | Manual |
| Vendor-neutral hosting | ✅ any host | ❌ WP Engine push | ❌ Netlify-aligned | ✅ | Manual |
| One-plugin install | ✅ single zip | ⚠️ npm + WPE Atlas | ⚠️ npm + WPGraphQL | ❌ | Manual |
| WP admin setup wizard | ✅ 4-step + diagnostic | ❌ | ❌ | ❌ | Manual |
| Preflight diagnostic (12 checks) | ✅ | ❌ | ❌ | ❌ | Manual |
| Frontend update agent | ✅ HMAC-signed daemon | ❌ | ❌ | ❌ | Manual |
| Headless-first Gutenberg blocks | ✅ 8 blocks | ❌ | ❌ | ❌ | Manual |
| ACF / Meta Box / Pods detection | ✅ auto | ⚠️ separate plugin | ⚠️ schema config | ❌ | Manual |
| Custom Code Block (HTML/CSS/JS) | ✅ 3 security modes | ❌ | ❌ | ❌ | Manual |
| WP-CLI commands | ✅ 6 commands | ❌ | ❌ | ❌ | Manual |
| Premium admin UI | ✅ | ❌ | ❌ | ❌ | n/a |
| Phone-home to vendor | ❌ never | ⚠️ WPE | ⚠️ Netlify | ❌ | n/a |
| Status (May 2026) | ✅ Active | ⚠️ Pivoting | ⚠️ Maintenance | 💀 Dead 2022 | n/a |
| License | MIT | MIT | MIT | Apache | n/a |
---
## Themes
Three reference themes ship with the Astro starter — picked in the setup wizard:
| Theme | Built for | Inspired by |
|---|---|---|
| 📰 **Blog** | Personal blogs, news, magazines | Substack · NYTimes Open |
| ⚙️ **Tech** | Developer blogs with code-heavy posts | Vercel Blog · dev.to |
| 📚 **Docs** | Documentation sites with sidebar + search | Vercel Docs · Stripe Docs |
Astro starter lives at [adityaarsharma/hatch-astro-starter](https://github.com/adityaarsharma/hatch-astro-starter). Pull it down with `npm create hatch@latest`.
---
## The premium admin UI
Hatch's admin panel is built on a scoped design system inspired by Linear / Vercel / shadcn:
- **Inter font** loaded from rsms.me (7KB cached)
- **9 semantic color tokens** matching the same `--hatch-*` CSS variables used in the frontend Astro starter
- **Heroicons** (outline, MIT) inlined as SVG strings — no extra HTTP requests
- **Custom CSS scoped to `.hatch-admin`** — zero pollution of WP core admin or other plugins
- **5-breakpoint responsive** — works on mobile wp-admin
- Components: cards, icon-boxes, pills, dots, status rows, notices, premium checkbox rows, modern form inputs with focus rings
Most WordPress plugins ship admin UIs that feel like 2014. Hatch feels like a 2026 product.
---
## FAQ
Do I need to run any of my own infrastructure to use Hatch?
No. Hatch is a single WordPress plugin. You install it on your own WordPress host. There's no Hatch Cloud (yet), no central server, no telemetry, no phone-home. The agent install script is served from your own WordPress.
Can I use this with my existing WordPress site?
Yes, with one important caveat: **WordPress should be on a non-public subdomain** (e.g. `cms.yoursite.com`), not your root. If you're on a root domain, Hatch will warn you and link to the migration guide. The migration is straightforward (DNS + WP config update) but you should do it before going live with a headless frontend.
Will it work with my Elementor / Divi / page builder site?
**No.** Page builders are frontend renderers — their output depends on PHP runtime that doesn't exist in a headless setup. For Elementor/Divi/Beaver sites: keep them as traditional WordPress. For headless: use Hatch Blocks (8 blocks ship in the plugin) or Astro components.
What about Faust.js / WPGraphQL?
You can install WPGraphQL alongside Hatch — they don't conflict. But Hatch doesn't require WPGraphQL. The whole REST API surface (`/hatch/v1/*` + `/wp/v2/*`) gives your frontend everything it needs.
How do I push updates to my frontend?
Three options. **Option 1:** Install the Hatch Agent (one curl command on your VPS) — then click "Update frontend now" in the WP admin. **Option 2:** Use SSH credentials (encrypted, whitelisted commands only). **Option 3:** Ignore the Frontend tab entirely and trigger your own deploy via GitHub Actions / Vercel / Netlify in response to the Hatch webhook.
Is the Custom Code Block safe?
Three layers of defense. Only users with `unfiltered_html` capability can save raw HTML/CSS/JS (default: administrators only). Lower-privileged saves are silently stripped. REST output to non-capable users also strips custom-code blocks. And there are three execution modes per block: inline (no JS), Shadow DOM (scoped), or full iframe sandbox.
How does Hatch make money?
The plugin is MIT-licensed and forever free. The maintainer ([Aditya Sharma](https://adityaarsharma.com/connect)) is available for headless WordPress migrations and custom work. A hosted Hatch Cloud is on the long-term roadmap (V2.5+) but only if there's clear demand — the OSS plugin will always be free.
What versions of WordPress / PHP are supported?
WordPress 6.4+ and PHP 7.4+. Tested up to WordPress 6.9 and PHP 8.3. Earlier versions may work but aren't tested. WP 7.0 (May 20, 2026) Abilities API integration is on the roadmap for V0.6.
What gets removed if I delete the plugin?
The uninstall hook removes **all** Hatch options from `wp_options` — webhook secret, agent credentials, SSH credentials, security settings, login slug, theme choice. Clean removal. No orphaned data.
---
## Roadmap
| Version | What ships | Status |
|---|---|---|
| **V0.1** | Companion plugin foundation, REST hardening, SEO/forms bridges | ✅ Shipped |
| **V0.2** | ACF/CPT detection, login hardening, App Password helper, tabbed admin | ✅ Shipped |
| **V0.4** | 8 Gutenberg blocks bundled into the WP plugin | ✅ Shipped |
| **V0.5** | Frontend Agent + SSH fallback + premium admin UI + setup wizard | ✅ Shipped (this release) |
| V0.6 | WP 7.0 Abilities API + MCP tool exposure | 🟡 Next |
| V0.7 | 16 more blocks (Gallery, Video, Tabs, Accordion, Pricing, Testimonial, Feature Grid, CTA, Embed, etc.) | 🔵 Planned |
| V1.0 | Stable, WP.org listing, docs site complete | 🔵 Planned |
| V1.5 | In-admin AI assistant (BYO API key, uses Abilities API) | 🔵 Planned |
| V2.5 | Hatch Cloud (hosted option, gated on 5,000+ active OSS sites) | 🔵 Long-term |
Full roadmap: [ROADMAP.md](ROADMAP.md)
Path from "well-architected" to "enterprise-proven": [docs/enterprise-readiness.md](docs/enterprise-readiness.md)
---
## Need help going headless?
Hatch is forever free and open-source. If you want a hand with the migration — DNS, hosting setup, theme customization, content migration — [Connect with Aditya](https://adityaarsharma.com/connect).
---
## Community
PRs welcome. Issues welcome. Build a new theme — there's a [THEME-CONTRACT.md](themes/THEME-CONTRACT.md). Build a module — there's a pattern. Write a tutorial — link us.
- **[GitHub Discussions](https://github.com/adityaarsharma/hatch/discussions)** — questions, ideas, showcase
- **[Issues](https://github.com/adityaarsharma/hatch/issues)** — bug reports, feature requests
- **[Twitter / X](https://twitter.com/adityaarsharma)** — release announcements
---
## License
**MIT.** Use it, fork it, ship it. Attribution appreciated, not required.
The WordPress plugin (`wp-plugin/`) is also compatible with the GPL v2 or later for WordPress.org distribution.
---
**Hatch — The Headless Engine for WordPress.**
[Download v0.5.0](https://github.com/adityaarsharma/hatch/releases/latest/download/hatch.zip) · [Documentation](https://hatch.adityaarsharma.com) · [Star on GitHub](https://github.com/adityaarsharma/hatch)
Built by [Aditya Sharma](https://adityaarsharma.com). MIT licensed.