Start here
@hulla/api
Declare an HTTP contract once, then bind typed clients and exhaustive server implementations to the transports and frameworks your application already uses.
@hulla/api is a typed HTTP contract library, not a backend framework. A contract declares the observable boundary—methods, paths, request representations, response statuses, and errors—while application code keeps ownership of business logic, framework state, caching, and deployment.
From that contract, @hulla/api/client creates a typed call tree and @hulla/api/server requires an exhaustive handler tree. An adapter then connects the server to Express, Fastify, Hono, a full-stack framework, a serverless host, or the Web Fetch API.
One contract, explicit boundaries
- Shared
Contract
Methods, paths, inputs, statuses, and representations.
defineContract - Server
Implementation
Exhaustive handlers, middleware, and request context.
defineServer - Host
Adapter
Framework routing, native context, and response writing.
expressAdapter - Client
Transport
One selected boundary: Fetch, in-process, IPC, or socket.
createClient
The contract module is safe to import from browser and server code. It contains schemas and transport declarations, but no database clients, secrets, or native framework objects. The server implementation imports the contract; the client imports only the contract and its chosen transport.
That split makes accidental server code in a browser bundle visible at the module boundary. It also lets one consumer use Fetch while another uses an in-process, MessagePort, or WebSocket transport without changing endpoint call signatures.
Choose only the boundary you need
| Need | Import | Owns |
|---|---|---|
| Declare the shared HTTP shape | @hulla/api | Routes, request/response representations, codecs, declared errors |
| Build typed calls | @hulla/api/client | Contract selection, client middleware, response decoding |
| Implement handlers | @hulla/api/server | Exhaustive handlers, server middleware, request context |
| Use Web-standard HTTP | @hulla/api/fetch | Fetch transport and Fetch server adapter |
| Avoid a network hop | @hulla/api/in-process | Direct transport through the same contract lifecycle |
| Mount a host framework | @hulla/api-* adapter package | Native routing, context, request reads, and response writes |
Core depends only on the Standard Schema specification. Zod, Valibot, and other compatible validators remain application dependencies, and a schema is used only where the contract explicitly supplies one.
What changed in 2.0
The previous procedure builder, plugin hooks, generated client runtime, and createApi() entrypoint are gone. Contracts now describe HTTP directly; clients are constructed directly from a contract or selection; server implementations are exhaustive; cache integrations are explicit parallel views; transports and native adapters are separate boundaries.
If you are upgrading, read the migration guide. For a new project, install the package and complete the quick start, then use the mental model to choose a transport and host adapter.