SpiderPublish Overview
A tenant-isolated runtime and marketplace for dynamic booking apps.
SpiderPublish is not a generic CMS. It is built in three distinct layers to ensure multi-tenant security, fast global edge delivery, and powerful management capabilities.
STORE (PostgreSQL)
FastAPI backend. Every authored thing lives here in a tenant-isolated row. Nothing is "on disk."
SERVE (Edge)
Cloudflare Workers read templates from KV and fetch content at request time. Blazing fast delivery.
MANAGE (MCP / CLI)
Dashboard, Model Context Protocol, and CLI all talk to the exact same STORE API endpoints.
Hard Gates
SpiderPublish employs two strict rules for any mutating operations:
- Tenant-Scope Verifier: Never mutate without ensuring the context is correct via
./scripts/verify-tenant-scope.sh. - Two-Phase Deploy Protocol: All production-altering actions must pass a dry-run/confirm flow. See the CLI documentation for details.
Five-Lock Tenant Defense
Every operation passes through five isolation locks before reaching tenant data. This ensures that no cross-tenant data leakage is possible, even during bulk operations or marketplace-wide deployments.
CLI & Setup
Install, authenticate, and configure your local development environment.
Installation
Install the SpiderPublish tools from our private NPM registry.
npm install -g @spideriq/cli --registry=https://npm.spideriq.aiAuthentication
Authenticate using a Personal Access Token (PAT). Generate this in Dashboard → Settings → API Keys.
export SPIDERIQ_TOKEN="client_id:api_key:api_secret"
spideriq auth loginMCP Server Setup
Configure the Model Context Protocol server for AI-assisted development.
{
"mcpServers": {
"spideriq": {
"command": "npx",
"args": ["--registry=https://npm.spideriq.ai", "@spideriq/mcp-publish"],
"env": { "SPIDERIQ_FORMAT": "yaml" }
}
}
}Two-Phase Deploy
For safety, deployment uses a dry-run confirmation token system. Every production mutation requires two steps:
# Step 1: Dry run — returns a confirm_token
spideriq deploy --dry-run
# Step 2: Confirm with the token
spideriq deploy --confirm=TOKEN_FROM_STEP_1STORE API
RESTful endpoints for programmatic content management.
Authentication
All endpoints require a Bearer token in the Authorization header.
Authorization: Bearer spideriq_pat_...Pages
GET /content/pages— List all pagesPOST /content/pages— Create a new pagePATCH /content/pages/:id— Update page blocks, SEO, layoutPOST /content/pages/:id/publish— Publish page changes
Components
GET /content/components— List all componentsPOST /content/components— Create componentPATCH /content/components/:id— Update HTML, CSS, JSPOST /content/components/:id/publish— Publish to edge
Deploy
POST /content/deploy— Trigger edge flush (requiresdry_run: truefirst)
Media
POST /content/media/upload— Upload images and assetsGET /content/media— List uploaded media
Component Guidelines
Rules for building components inside SpiderPublish's Shadow DOM runtime.
Shadow DOM Rules
Components render in an isolated Shadow DOM context. Never use document.querySelector. Traverse from a known root:
var root = this.closest('.wrap').getRootNode();
var el = root.querySelector('.target');Event Listeners
The safest pattern for initialization logic is using a hidden SVG onload or inline onclick handlers:
<svg width="0" height="0" style="position:absolute;opacity:0"
onload="yourInitCode()"></svg>Theme Tokens
Never hardcode brand colors. Use injected CSS variables that flow per-tenant:
var(--spider-primary)— Brand accent colorvar(--spider-text)— Primary text colorvar(--spider-bg)— Background colorvar(--spider-surface)— Card/surface color
Size Constraints
Components must stay lean for edge delivery performance:
- JS: ≤ 2 KB gzipped per component
- No external libraries except CDN allowlist (Inter, Outfit, DM Mono)
- prefers-reduced-motion gating is mandatory for animations
Templates
Page templates control layout structure and component rendering order.
Available Templates
SpiderPublish ships with three built-in templates. Each defines how blocks are rendered on the page:
Landing
Full-width, no sidebar. Used for Home, Pricing, 404, and marketing pages.
Docs
25/75 split with sticky sidebar navigation. Used for Documentation and guides.
Blog
Content-focused single column with author, date, and tag metadata. Used for posts.
Assigning Templates
Set a template when creating or updating a page via the API:
PATCH /content/pages/:id
{ "template": "landing" }Block Order
Blocks are rendered in array order. The header and footer components are typically first and last:
{
"blocks": [
{ "type": "component", "component_slug": "modern-header" },
{ "type": "component", "component_slug": "hero-section" },
{ "type": "component", "component_slug": "cool-footer" }
]
}Booking
Build and embed dynamic booking flows with the form runtime.
Form vs Booking
SpiderPublish treats forms and booking flows as the same entity. Both use kind to distinguish behavior:
kind: "form"— Standard contact/lead formkind: "booking"— Date/time selection + availability check
Both render at /f/<form-id> and can be embedded via iframe or Shadow DOM component.
Creating a Form
POST /content/forms
{
"name": "Contact Us",
"kind": "form",
"fields": [
{ "type": "text", "label": "Name", "required": true },
{ "type": "email", "label": "Email", "required": true },
{ "type": "textarea", "label": "Message" }
]
}Embedding
Forms are embedded using the SpiderPublish form component. The URL pattern is always:
https://<tenant-domain>/f/<form-id>Submissions
All submissions are stored in the STORE and accessible via API or Dashboard. Webhook notifications can be configured per-form.
Deploy Protocol
How content moves from STORE to the global edge network.
Deploy Pipeline
Every deploy follows a strict three-step pipeline to ensure zero-downtime updates:
1. Dry Run
Validates all content, checks for broken references, and returns a preview URL + confirm token.
2. Confirm
Uses the confirm_token from dry run to atomically flush content to Cloudflare KV.
3. Propagate
Edge workers pick up the new KV entries within seconds. Global propagation under 30s.
Custom Domains
After deploy, content is served on the primary domain. Custom domains can be configured via:
POST /content/domains
{
"domain": "example.com",
"type": "custom",
"ssl": "auto"
}Rollback
Every deploy creates an immutable snapshot. Roll back to any previous version instantly:
POST /content/deploy/rollback
{ "snapshot_id": "snap_abc123" }Marketplace
Publish reusable components to the SpiderPublish marketplace.
Overview
The marketplace allows component authors to publish UI blocks that any tenant can browse and insert into their site. Components are reviewed, versioned, and propagated automatically.
Publishing a Component
Use the content_create_component MCP tool or the REST API. Required metadata:
- name — Display name in the catalog
- category — One of: hero, feature, cta, pricing, testimonial, footer, header, form, gallery, custom
- mood — Visual mood: minimal, bold, playful, corporate, luxury
- replication_prompt — Natural language description for AI-assisted customization
Versioning
Components use semantic versioning. Each publish creates a new version. Tenants can pin to a specific version or use latest.
PATCH /content/components/:id
{
"version": "2.1.0",
"html_template": "...",
"css": "..."
}Tenant Insertion
Tenants browse the marketplace in the Dashboard and insert components as blocks on their pages. The component CSS is scoped via Shadow DOM — no style conflicts.