jampress.pw
Philosophy Docs Roadmap Playground GitHub

Documentation

Philosophy Three tracks, modular scaling, and the foundation rules that shape every package. Architecture Stable viewer contracts with swappable provider/storage internals. Security Threat model, token/session controls, and rate-limit requirements. Roadmap Phase-by-phase path from DIY auth to WordPress bridge and adapters. Auth Adoption Plan Concrete rollout order and milestones for zip, lobpress, inbox, DesBio, and DBScript. Host App Integration How Astro and Workers apps wire middleware, hooks, and routes. Provider Adapters The AuthAdapter contract and migration path across login providers. Data Model D1/MySQL schemas for identities, sessions, tokens, and rate limits.

Jampress Philosophy

Jampress is a toolkit for the full spectrum of web development — jamstack, WordPress, and everything in between. This document explains what we build, what we don't, and why.

Three parallel tracks

Jampress supports three parallel (and often overlapping) tracks. Each track is first-class. A package in one track isn't a second-class citizen because it doesn't touch the others.

1. Traditional jamstack. Static SSG sites, edge-rendered apps, Cloudflare-native stacks. Auth, dashboards, forms, commerce — packages that work standalone in a pure jamstack context.

2. Traditional WordPress. Classic WordPress sites that stay WordPress. Plugins that improve WP workflows without requiring any decoupling: better auth, better forms, better updates, better admin tools.

3. Bridging and hybrid. The connective tissue between jamstack and WordPress. Headless content export, auth continuity across decoupled splits, forms that post from Astro to WordPress, WooCommerce flows in Astro frontends.

These tracks exist because real agencies and real teams work across all of them.

Modular scaling

Underlying all three tracks: every package works standalone and grows with you.

  • DIY magic-link auth scales to Better Auth or Firebase
  • Static content scales to dynamic
  • Simple dashboards scale to real-time streams
  • Local forms scale to headless form bridges
  • Basic auth scales to federated SSO

Start with what you need. Add more as your scope grows. Don't install the Firebase adapter on day one if you're prototyping with magic-link. Don't add real-time streaming to a dashboard that refreshes hourly. Each package is opinionated about its defaults but accommodates growth without rewrites.

Foundation requirement

Every jampress package MUST have a Cloudflare-native or PHP+MySQL foundation. This is non-negotiable for v1 of any package.

Why this rule exists: Cloudflare and PHP+MySQL are the infrastructure we run. Everything else adds operational overhead, vendor relationships, and failure modes we're not staffed to support. A package that requires Postgres on AWS, Redis on Upstash, or Node.js on Fly.io isn't jampress — it's a different project.

Track-specific requirements:

  • Jamstack track: Cloudflare Workers + D1 + R2 + KV. Durable Objects for stateful workloads.
  • WordPress track: PHP 8.1+ and MySQL. No runtime requirement beyond what major managed WP hosts support.
  • Bridging track: Must span the two foundations — Cloudflare on one side, PHP+MySQL on the other.

What's permitted once the foundation is met: Additional infrastructure may be added as optional adapters. Auth: DIY (D1) → Better Auth → Firebase → Auth0. Storage: D1 → MySQL → Supabase. Email: Zeptomail → Cloudflare Email Send → Resend. Dashboards: Durable Objects → Polygon-direct → broker-specific.

The default is always Cloudflare or PHP+MySQL. Additional adapters are opt-in enhancements, never baseline requirements.

Extenuating circumstances: If a package genuinely cannot function on the mandated foundation, it may petition for an exception. The petition must document why the foundation is insufficient, what specific feature cannot be replicated, what operational burden the exception adds, and why this package still belongs in jampress. Petitions should be rare. "We want Postgres because we're familiar with it" is not a petition.

SSG and UI framework defaults

Astro 6 is the default and priority SSG. All jampress packages targeting the jamstack track are designed and tested against Astro 6 on Cloudflare Workers first. Support for other SSG frameworks (Next.js, SvelteKit, Nuxt, Eleventy, etc.) is a secondary or tertiary concern — not refused, but not prioritized.

Preact is the default UI framework for jampress components. This follows from the foundation rule: Preact is what reliably works on Astro 6 + Cloudflare Workers today. React has known build failures in this stack that Preact does not.

Both frameworks are supported via subpath exports. When a package ships interactive UI components, it provides both framework bindings in a single package:

import { SubscribeForm } from '@jampress/auth-widget-subscribe/preact';  // default, recommended
import { SubscribeForm } from '@jampress/auth-widget-subscribe/react';   // when needed

The package's core logic (state machines, validation, fetch calls) is framework-agnostic TypeScript. The Preact and React components are thin rendering shells around that shared core. This prevents implementation drift and keeps both flavors synchronized.

Preact is still the recommended default. The React entry point exists for apps built on stacks where Preact isn't viable — but if you're on Astro 6 + Cloudflare Workers, Preact is the path of least resistance.

WordPress plugins use vanilla JS. No React/Preact in WordPress admin contexts — WP plugins target the WordPress runtime and its constraints.

What belongs in jampress

A package belongs in jampress if:

  • It fits one of the three tracks (jamstack, WordPress, bridging)
  • It has a Cloudflare-native or PHP+MySQL foundation as its default
  • It follows modular scaling (works standalone, grows into more)
  • It targets Astro 6 for SSG integration (if applicable)
  • It ships UI as Preact first (with optional React entry point)

What doesn't belong

  • Packages requiring infrastructure outside Cloudflare or PHP+MySQL as the default
  • Packages that only work on Node.js servers
  • Packages that require Postgres-specific features we can't replicate on D1
  • Packages targeting SSG frameworks other than Astro as their primary target
  • Packages that don't fit any of the three tracks
  • Tools unrelated to web development

Philosophy is revisitable

Nothing here is permanent. If Astro's Cloudflare adapter gains reliable React support, the Preact-first rule gets reassessed. If Cloudflare releases a Postgres-compatible service, the database options expand. If our team's ops capacity grows, the foundation rule might loosen.

But changes to the philosophy are deliberate, documented, and discussed — not drive-by exceptions during package development.