Porulle

Headless commerce for TypeScript. Self-host. Own the stack.

Porulle (pronounced poh-ROO-leh) is a TypeScript-first headless commerce framework. Install it into any TypeScript project, point it at PostgreSQL, and you have a hardened REST API in minutes.

bunx @porulle/cli init my-store
cd my-store && bun install && bun run db:push && bun run dev

The API is live at http://localhost:4000. The OpenAPI explorer is at /api/reference.

Get Started

Introduction — what Porulle is and who it is for.

Install — prerequisites, packages, database setup.

Quickstart — a working commerce API in five minutes.

Building a Store

Authentication — roles, API keys, social login.

Email Notifications — order confirmations, password resets, transactional sends.

Analytics — SQL-backed metrics with scoped access.

Extending Porulle

Hooks — intercept any operation with before/after handlers.

Custom Tables — add app-level Drizzle tables to the org-scoped schema.

Payment Adapter — implement the contract for any payment rail.

Frontend Integration

Next.js — Hono mounted in a route handler.

TanStack Start — server functions calling LocalAPI in-process.

Typed SDK Client — @porulle/sdk + React Query bindings.

Running in Production

Deploy — Bun, Node.js, Cloudflare Workers, Fly.io.

Multi-Tenancy — B2C single-storefront vs B2B multi-tenant.

Webhooks and Audit — signed delivery + idempotency.

Reference

Configuration — every defineConfig option.

REST API — 116 paths, 146 operations.

Adapters — database, payment, storage, search.

Concepts

Architecture — the kernel, modules, adapters, interfaces.

Plugin Architecture — why plugins are config transforms.

Result Types — why services return Result<T>.

Tutorials

Your First Store — products, inventory, cart, checkout end-to-end.

Build a Loyalty Plugin — hooks, schema, routes in one plugin.

Tea Shop POS — terminals, shifts, split payment, Z-reports.

Status: v0.1.0 alpha. The REST API, multi-tenant kernel, plugin contract, and adapter contracts are stable. Agent-native primitives (principal model, multi-protocol gateway) are Phase 2. See the Security Model for the full threat model and Phase 2 roadmap.