DOCUMENTATION
Everything you need to understand and ship PipWeb.
Architecture, runtime, trust, migration, package distribution, deployment and release acceptance in one reference.
What PipWeb is
PipWeb is PluginPip Ltd's full-stack TypeScript application framework. Its architectural centre is the Application Graph, not a filesystem router or a particular renderer.
The graph compiles capabilities, surfaces and flows into a validated model that can be inspected by the runtime, development tooling and machine interfaces.
React is the first web renderer and Node is the first runtime. Neither is intended to be the permanent architectural boundary of the framework.
- Explicit over magical
- TypeScript-first
- Web standards at runtime boundaries
- React-first with a renderer-independent core
- Node-first with a deployment-independent core
- Human and machine interfaces are peers
- Security and observability are part of the architecture
Current runtime and toolchain requirements
The current alpha line targets Node.js 24 or newer and a TypeScript-first workflow. PipWeb workspace package versions are synchronised.
- Node.js 24+
- TypeScript 5.9+
- React 19 for the current web renderer
- pnpm for framework workspace development
- Private PluginPip package registry for current alpha packages
Start from the production product starter
The product starter gives a new application a production-oriented baseline with canonical metadata, sitemap.xml, robots.txt, a web manifest and favicon support.
pipweb create my-product --template productModel the application before the transport
The Application Graph is the compiled model of the whole application. It joins capabilities, surfaces and flows and validates their references before deployment.
The graph is inspectable architecture rather than framework convention hidden across folders.
- Capabilities describe reusable business or infrastructure abilities
- Surfaces expose capabilities to consumers
- Flows compose capability actions into multi-step processes
- Graph validation detects invalid references and unsafe exposure
Define what the application can do
Capabilities are version-controlled application dependencies, not runtime-installed plugins. They can describe actions, dependencies, trust requirements and entitlement boundaries.
const catalogue = defineCapability({
name: "catalogue",
provides: ["catalogue.read", "catalogue.search"],
actions: [{
name: "catalogue.search",
trust: {
actors: ["anonymous", "human", "agent", "service"],
effect: "read",
risk: "low",
approval: "none",
audit: "metadata"
}
}]
});Expose one capability through multiple interfaces
A surface is an interface over a capability action. The same domain logic can power browser UI, JSON APIs and agent-facing actions without duplicating the capability itself.
- web
- API
- agent
- realtime
- mobile
const api = defineSurface({
name: "catalogue-api",
kind: "api",
route: "/api/products",
method: "GET",
capability: "catalogue",
action: "catalogue.search"
});Compose durable business work
Flows represent ordered capability actions for processes such as onboarding, quote-to-order, provisioning, invoicing or renewal.
The current runtime supports durable execution with retry, idempotency and compensation primitives.
- Ordered capability actions
- Retry policy
- Idempotency
- Compensation actions
- Principal propagation
- Entitlement propagation
- Approval evidence propagation
Compile the whole system into one definition
An application combines its capabilities, surfaces and flows into the graph consumed by the runtime.
export const application = defineApplication({
name: "my-app",
version: "0.1.0",
capabilities: [catalogue],
surfaces: [web, api, agent],
flows: [enquiry]
});Bind graph intent to executable behaviour
Capability runtimes connect declared actions to executable handlers. Application runtime definitions then bind those capability runtimes to web, API or other surfaces.
PipWeb keeps execution context available to policy, entitlement, approval and audit layers rather than burying those concerns inside handlers.
Server-render React without making React the architecture
PipWeb supports React server rendering, streaming SSR, hydration data and hashed client bundles while keeping capabilities and flows independent from React.
- Server-rendered HTML
- Streaming SSR
- Hydration data
- Hashed client bundles
- Production asset references
Production document metadata is first-class
The React document layer supports production metadata and the SEO package generates machine-readable site files.
- Canonical URLs
- robots directives
- Theme colour and web manifest
- Icons and alternate-language links
- Open Graph
- Twitter/X cards
- JSON-LD
- sitemap.xml
- robots.txt
Production web runtime behaviour
The runtime includes request parsing and delivery primitives expected by production applications.
- JSON request parsing
- URL-encoded forms
- multipart/form-data
- File uploads
- Redirects
- Server-Sent Events
- Static asset delivery
- HEAD support
- ETags and 304 responses
- Immutable caching
- Byte ranges
Routed realtime endpoints
PipWeb can expose routed WebSocket endpoints with route parameters, origin policy and payload limits.
Signed session cookies
The runtime can issue and verify HMAC-signed session cookies for applications that need server-managed session state.
Framework-level request protections
Security controls live at the runtime boundary so applications do not have to reimplement baseline protections per route.
- Security headers
- CORS
- CSRF protection
- Request limits
- Correlated diagnostics
Make authority machine-readable
Agent-exposed actions require explicit trust metadata. The runtime can resolve a principal, enforce actor and permission requirements and ask policy or approval layers whether execution may proceed.
- Permitted actor kinds
- Required permissions
- Side-effect classification
- Risk classification
- Approval mode
- Audit level
Machine identity through PipKey
The PipKey integration can resolve agent principals from verified machine credentials. Verification can include audience, environment, scopes and linked entitlement evidence.
Admin PipKey credentials are rejected by default for agent execution.
Separate product entitlement from identity
Capability execution can declare organisation, product, module, grant and claim-constraint entitlement requirements independently from authentication and permissions.
- Organisation entitlement
- Product entitlement
- Module entitlement
- Grant requirements
- Claim constraints
- Fail-closed resolution
Pause high-risk work before the handler runs
Actions declaring human approval can halt before execution. Approval evidence is tenant-scoped, single-use and bound to the exact request fingerprint.
Self-approval is forbidden by default and consumed approvals cannot be replayed.
- Pending approval creation
- Safe approval identifiers
- Dedicated approval execution reference
- Exact request fingerprint binding
- Atomic approved-to-consumed transition
- Cross-organisation concealment
- Approval evidence attached to execution receipts
Durable evidence without raw payload leakage
PipWeb emits privacy-minimised execution receipts with stable IDs and started, succeeded or failed lifecycle states.
A PostgreSQL-backed receipt store supports filtered lookup by organisation, principal, capability, action, status and time. Required receipt mode can fail closed before execution if durable evidence cannot be persisted.
Operate the application, not just the routes
The runtime exposes liveness, readiness and graph diagnostics and supports OpenTelemetry instrumentation.
- /_pip/health
- /_pip/ready
- /_pip/graph
- OpenTelemetry instrumentation
- Correlated request diagnostics
Create, inspect, diagnose and migrate
The PipWeb CLI is the main developer entry point for creating applications, inspecting the compiled graph, running diagnostics and building migration plans.
- create
- doctor
- inspect
- audit
- migrate next
pipweb create my-product --template product
pipweb doctor
pipweb inspect dist/app.js
pipweb audit dist/app.js
pipweb migrate next ../next-app --output ../pipweb-appGenerate static web and API artifacts
PipWeb can generate static HTML and API artifacts and apply explicit cache and revalidation policies where an application does not need per-request execution.
Use infrastructure without making it the framework
PipWeb's production integrations are adapters rather than architectural dependencies.
- PostgreSQL
- Valkey
- NATS
- S3-compatible storage
- OpenTelemetry
Node and container deployment baseline
The current deployment baseline includes Node and Docker adapters. Additional deployment targets remain on the roadmap.
Semantic migration rather than blind file copying
The migration planner understands common App Router and Pages Router structures, routes, handlers, layouts, server actions, metadata and framework-specific imports.
Generated migration output includes executable PipWeb scaffolding, source transformation, machine-readable reporting and explicit automatic/review/unsupported classification.
- Static, dynamic and catch-all route translation
- App Router and Pages Router discovery
- Layouts and route handlers
- Server-action discovery
- Metadata and static-parameter detection
- Revalidation and dynamic-rendering hints
- Secret-safe .env handling
- migration-report.json
- MIGRATION.md
Compatibility belongs to PipWeb, not Next.js internals
The PipWeb-owned compatibility package translates common Next.js application APIs while keeping migrated applications on PipWeb runtime ownership.
- next/link
- next/image
- next/navigation
- next/cache
- next/server
- App Router route handlers
- Simple server actions
- Pass-through middleware/proxy patterns
- Nested layout composition
Private PluginPip package distribution
Current alpha packages are distributed through the PluginPip Gitea npm registry. All @pluginpip/pipweb-* packages share the same framework version.
@pluginpip:registry=https://git.pluginpip.co.uk/api/packages/PluginPip/npm/
//git.pluginpip.co.uk/api/packages/PluginPip/npm/:_authToken=${GITEA_NPM_TOKEN}Synchronized Semantic Versioning
All PipWeb workspace packages use the same version. CI rejects malformed or divergent package versions.
Before 1.0, substantial capability additions still advance the minor line instead of hiding large changes in alpha counters.
- alpha.N: active feature development
- beta.N: feature-complete line under production testing
- rc.N: release candidate
- stable: prerelease suffix removed after acceptance
- patch: backward-compatible hardening or fixes
pnpm version:check
pnpm version:set -- 0.3.0-alpha.10Ship only after the framework gates are green
PipWeb release acceptance is evidence-based. Package publication and consumer installation are part of the release proof, not an afterthought.
- pnpm install --frozen-lockfile
- pnpm version:check
- pnpm build
- pnpm typecheck
- pnpm test
- pipweb doctor
- pipweb inspect
- pipweb audit
- Pack/publish synchronized packages
- Verify a clean consumer install from the private registry
Release manifests, SBOM and provenance
PipWeb can produce release manifests, CycloneDX SBOMs and SLSA provenance to strengthen software supply-chain evidence.
What alpha.10 means today
PipWeb 0.3.0-alpha.10 is a production-capability alpha with a framework-level quality baseline. The core build, typecheck, tests, doctor, inspect and audit gates are green, all 20 packages are published privately, and a clean product-site consumer verifies critical CSS, metadata, accessibility defaults and production deployment output.
PluginPip-owned applications are being used as acceptance workloads before broader developer adoption.
- Application Graph and runtime are operational
- Web, API and agent surfaces are operational
- Trust, entitlements, human approval and audit receipts are operational
- Private package distribution is operational
- Product-site starter is operational
- Developer ergonomics, HMR, wider deployment adapters and broader compatibility testing remain active work
Keep the docs tied to the framework.
This reference is intentionally grounded in the current PipWeb source and release line. When capabilities change, the public documentation should move with the same release.