Build with Palbase
Everything you need to ship with Palbase — the backend SDK, web and iOS client SDKs, and the CLI.
Getting Started
Introduction
What Palbase is — managed backend, database, auth, storage, and client SDKs in one platform.
Quickstart
Create a project, write your first controller, deploy with palbase push, and call it from a client.
Architecture
How Palbase code is shaped: one module per domain declaring what exists, thin controllers, services that hold the logic and arrive by constructor, zod schemas in the module's dto, and the database declared in one file.
Project Structure
How a Palbase backend project is laid out: modules/<domain>/ with its module, controllers, services and dto, the db/ schema, tests, and the generated files you commit.
Backend SDK
Overview
@palbase/backend — modules that declare what exists, class controllers, typed endpoints, and the ten ambient singletons (Database, Auth, Documents, Storage, Cache, Secrets, Log, Notifications, Flags, Realtime).
Modules & Dependency Injection
@Module's four lists, why a class no module names does not exist, and injection by constructor type — no @Inject, no useFactory, no forwardRef.
Controllers & Routing
@Controller classes, HTTP method decorators, route options, and rate limiting.
Request Validation
@Body, @QueryParams, @Param, and @Headers with zod schemas.
Authentication
Secure-by-default routes, @User and @OptionalUser, roles, and request metadata.
Responses & Errors
Response schemas from return types, built-in error classes, and typed errors with defineError.
Localization
t() — your backend's sentences in the caller's language: the palbase/strings/ table, palbase build --add, and AI translation with --translate on your own key.
Database
Typed queries with the Database service: tables, transactions, and raw SQL.
Schema
Define your Postgres schema in TypeScript with defineTable, defineSchema, column builders, and extensions.
Schema migration guide
Moving a db/schema.ts project to the current DSL: one file per schema, defineTable bindings, ownedByUser and reference thunks.
Search
Full-text and vector search declared beside your columns, read through one typed method.
Row-Level Security
RLS policies in the schema DSL, auth.uid(), and the asService() escape hatch.
Schema changes
There are no migration files: palbase db plan shows what would change, db apply changes it.
Documents
The Documents service — a Firestore-style document store with collections and queries.
Storage
The Storage service — buckets, uploads, downloads, signed URLs, and variants rendered at upload.
Direct Uploads
The @Upload decorator — let clients PUT bytes straight to storage, with the handler as the completion gate.
Cache
The Cache service — in-process JSON key-value state with TTLs and single-flight getOrSet.
Secrets
The Secrets service — API keys and credentials read by name, rotated without a deploy.
Scheduled Jobs
Cron-scheduled work with @Job classes and a run() method.
Webhooks
Receive provider webhooks (Stripe, GitHub, …) with @Webhook classes and @On, or verify your own with signature.
Event Hooks
React to auth, document and file events with @Hook (blocking) and @On (listening) classes.
Outbound Network
A backend has no ambient network — declare every host it may reach with palbase egress.
Flags
Read feature flags and write per-user overrides from backend code.
Notifications
Send push, email, SMS, and in-app inbox messages through the Notifications service.
Realtime
Broadcast events to connected clients with Realtime.broadcast.
Streaming responses
@Sse — write the answer as it is produced and let the client read it as it arrives.
Channels
Declare which realtime channels exist and who may subscribe, publish or write state.
Rooms
@Room classes and their six hooks — who joined, who left, and the one moment the last device goes.
Test Users
Disposable test accounts and their seed data, typed against your schema.
Testing
palbase test's two layers: services against fakeDatabase() with no stack, and the HTTP layer against a real deployment.
Web SDK
Overview
@palbase/web — the Palbe client SDK for the browser. One entry point: pb.
Codegen
palbase link and palbe-gen — generate the fully typed client for your backend.
Auth
Sign-up, sign-in, sessions, OAuth, magic links, and OTP in the browser.
Calling Your Backend
Typed endpoint namespaces, call options, and the request pipeline.
Error Handling
BackendError kinds and the generated typed error classes.
Uploads
Multipart file uploads with progress, constraints, and backend pairing.
Flags
Feature flags with live polling, typed getters, and subscriptions.
Realtime
WebSocket channels: subscribe to broadcasts and send client events.
Analytics
Event capture, identify, screen tracking, and GDPR opt-out.
Messaging
End-to-end encrypted DMs and group chats in the browser with Web-MLS.
Calls
Voice and video calls over WebRTC, scoped to messaging groups.
Next.js
Server Components, the proxy that refreshes the session, and the OAuth callback route.
React Hooks
useUser, useSession, useFlag, useFlags, and useChannel.
iOS SDK
Overview
Palbe — the Swift SDK for iOS. One entry point: pb, configured automatically from codegen.
Codegen
palbase link and palbase spec — typed Swift endpoint clients committed to your Xcode project.
Auth
Email, Apple, Google, OTP, and magic-link sign-in with persistent sessions.
Calling Your Backend
Generated typed calls with typed throws, and the pb.call escape hatch.
Error Handling
BackendError, AuthError, and generated per-endpoint failure enums.
Uploads
Multipart file uploads with progress and client-side constraints.
Flags
Observable feature flags — synchronous reads, SwiftUI re-rendering, live sync.
Realtime
Channels over a shared WebSocket — subscribe and publish from the app.
Analytics
Fire-and-forget event capture with automatic identity binding.
Messaging
End-to-end encrypted chats — DMs, groups, media, presence, typing, and read receipts.
Voice & Video Calls
End-to-end encrypted voice and video calls — participants, host moderation, and cross-device transfer.
App Attest
Automatic device attestation — behavior, errors, and why it never runs off a physical iPhone.
Debug Console
The in-app network + log console — what it records, how to open it, and pushing your own entries.
CLI
Overview
Install the palbase CLI, log in, and learn what a directory is bound to.
Running It Locally
palbase start and stop — a whole Palbase on your machine, rebuilding as you save, and which verbs act on it.
Linking a Checkout
palbase link binds a directory to a project — what it writes, and which file wins.
Projects & Linking
init, project create/list/status/delete, clone, API keys, and members.
Deploying
build, plan, push and pull — what travels, deploy history, rollback, and logs.
Database
db plan, db apply and db query against the stack running on this machine.
Secrets
secret set, list and remove — and palbase run, which hands the values to one command.
Codegen
palbase link and spec write the per-environment contract; three generators read it, and palbase build writes palbase-env.d.ts.
Stack Settings
storage, flags, egress and notification senders — written straight to the stack, effective immediately.
Auth Settings
palbase auth — settings, providers, sessions, audit, templates, and MFA on the linked stack.
Test Users
test-user create, templates, list, clone, and delete.
Debug
debug tail and debug attach — watch an app's in-app console from the terminal.