# Installation

> Install the core package and the integration for your server.

## Useful when

- You are starting a new TypeScript API.
- You need to know which adapter or transport package belongs in each application.

Install `@hulla/api` to define a contract and create a client or server. Add an adapter package if you're serving the API through a framework or platform listed below.

**Install the validated core** — Start with @hulla/api and a runtime schema library.

Run this in the workspace package that owns the shared contract. The examples use Zod, so installing it now
gives you the recommended runtime-validated path through the quick start.

### Run with bun

```sh
bun add @hulla/api@2.0.0 zod
```

### Run with npm

```sh
npm install @hulla/api@2.0.0 zod
```

### Run with pnpm

```sh
pnpm add @hulla/api@2.0.0 zod
```

### Run with yarn

```sh
yarn add @hulla/api@2.0.0 zod
```

### Optional agent skill

> **Tip: Working with a coding agent?**
>
>
>
> Install [api](https://github.com/hulladev/skills/tree/main/skills/api) from the [hulladev/skills repository](https://github.com/hulladev/skills) for guidance on shared contracts, server/client boundaries, and adapters. Run this in your application directory:
>
> ### Run with bun
>
> ```sh
> bunx --bun skills add hulladev/skills --skill api
> ```
>
> ### Run with npm
>
> ```sh
> npx skills add hulladev/skills --skill api
> ```
>
> ### Run with pnpm
>
> ```sh
> pnpm dlx skills add hulladev/skills --skill api
> ```
>
> ### Run with yarn
>
> ```sh
> yarn dlx skills add hulladev/skills --skill api
> ```
>
> Choose your agent in the installer and [check compatibility with your package version](https://hulla.dev/docs/cli/agent-skills.md#keep-guidance-aligned-with-your-dependencies).

> **Tip: bring your preferred validator**
>
> `@hulla/api` accepts any' '
> Standard Schema-compatible
> library. Replace Zod with Valibot, ArkType, Effect Schema, or another
> compatible implementation; the API contract does not change.

Type-only declarations are also available for already-trusted values.
They preserve compile-time types but do not validate real input or
output. See' '
contract declarations when that
tradeoff is intentional.

**Connect the server boundary** — Mount the implementation into the host that receives requests.

A server adapter translates the host's native request into a contract call, provides request context, and
turns the declared result back into the host's response. Only server code imports this adapter.

- **Web-standard hosts:** use the built-in [`@hulla/api/fetch`](https://hulla.dev/docs/api/transports/fetch.md) entrypoint. Follow the [runtime guides](https://hulla.dev/docs/api/runtimes.md) for Bun, Deno, Vercel, and other Fetch-compatible hosts.
- **Native servers:** [`@hulla/api-node`](https://hulla.dev/docs/api/servers/node-http.md), [`@hulla/api-express`](https://hulla.dev/docs/api/servers/express.md), [`@hulla/api-fastify`](https://hulla.dev/docs/api/servers/fastify.md), [`@hulla/api-hono`](https://hulla.dev/docs/api/servers/hono.md), [`@hulla/api-h3`](https://hulla.dev/docs/api/servers/h3.md), [`@hulla/api-elysia`](https://hulla.dev/docs/api/servers/elysia.md), [`@hulla/api-koa`](https://hulla.dev/docs/api/servers/koa.md), or [`@hulla/api-nestjs`](https://hulla.dev/docs/api/servers/nestjs.md).
- **Full-stack frameworks:** [`@hulla/api-next`](https://hulla.dev/docs/api/full-stack/next.md), [`@hulla/api-tanstack-start`](https://hulla.dev/docs/api/full-stack/tanstack-start.md), [`@hulla/api-react-router`](https://hulla.dev/docs/api/full-stack/react-router.md), [`@hulla/api-solid-start`](https://hulla.dev/docs/api/full-stack/solid-start.md), [`@hulla/api-sveltekit`](https://hulla.dev/docs/api/full-stack/sveltekit.md), [`@hulla/api-nuxt`](https://hulla.dev/docs/api/full-stack/nuxt.md), or [`@hulla/api-astro`](https://hulla.dev/docs/api/full-stack/astro.md).

Install one server adapter in the application that owns the listener or framework route. The shared contract
package should not depend on Express, Next.js, Node.js, or another host.

**Connect the client boundary** — Choose how typed calls travel from the caller to the server.

A client transport carries a contract-shaped call. It does not mount routes or own server middleware. Most
applications begin with one of the two transports already included in `@hulla/api`.

- **Same process:** use [`@hulla/api/in-process`](https://hulla.dev/docs/api/transports/in-process.md) in server-rendered code, tests, or another trusted process that can import the implementation.
- **HTTP:** use [`@hulla/api/fetch`](https://hulla.dev/docs/api/transports/fetch.md) in browsers, mobile clients, services, and server-side HTTP calls.
- **Workers or desktop IPC:** install [`@hulla/api-message-port`](https://hulla.dev/docs/api/transports/message-port.md).
- **Dedicated socket:** install [`@hulla/api-websocket`](https://hulla.dev/docs/api/transports/websocket.md).

The client imports the contract and its chosen transport. It imports the implementation only for an
in-process call—never for Fetch, MessagePort, or WebSocket.

Once direct calls work, optionally add [`@hulla/api-control`](https://hulla.dev/docs/api/integrations/control.md),
[`@hulla/api-tanstack-query`](https://hulla.dev/docs/api/integrations/tanstack-query.md), or
[`@hulla/api-swr`](https://hulla.dev/docs/api/integrations/swr.md). These wrap an existing client; they do not replace its
transport.

**Verify one vertical slice** — Prove the contract, implementation, and client before adding framework setup.

Build the first route in process so a listener, proxy, or framework cannot hide contract mistakes. The quick
start gives you three small modules:

1. `contract.ts` declares and validates what crosses the boundary.
2. `implementation.ts` contains server-only behavior.
3. `example.ts` creates a typed client, calls the route, and prints the created task.

When that call works, the core setup is complete. Keep the in-process transport when the caller stays beside
the server. For a browser or remote caller, move on to the client transport from step 3 and mount the same
implementation with the server adapter from step 2.

[Build the task API quick start →](https://hulla.dev/guides/api/quick-start.md)