AuraStack Router

`createClient`

The createClient function provides a declarative client API to invoke endpoints defined via createRouter. It offers fully type-safe access to HTTP methods, route definitions, and Zod validations, ensuring that all required values are strictly inferred and validated.

For complete type inference, the router type must be passed as a generic argument.

import { createClient } from "@aura-stack/router/client"
import { router } from "@/index.ts"

export const client = createClient<typeof router>({
  baseURL: "http://localhost:3000",
})

Overview

This documentation provides a comprehensive guide to the createClient API, covering everything from basic usage to advanced type inference.

Key Concepts
Type Inference
API Reference
- Parameters
- Returns

Key Concepts

The createClient function only offers type inference when the router type is provided as the first generic argument. Without it, the function cannot infer the API structure.
Type inference covers endpoint paths, HTTP methods, and values validated by Zod schemas.

Type Inference

To enable type safety and inference for the client API, the router type must be explicitly provided.

The client API can be imported from the main entry point / or /client.

API Reference

Parameters

The createClient function accepts a configuration object to customize the client instance.

import type { Router, InferEndpoints, Client, HTTPMethod, ClientOptions } from "@aura-stack/router/types"

function createClient<InferRoute extends Router<any>>(options: ClientOptions): Client<InferEndpoints<InferRouter>>

Parameter	Type	Description
`baseURL`	`string`	The base URL where the router is hosted.
`basePath`	`/${string}`	An optional base path to prepend to all requests.
`headers`	`IncomingHttpHeaders`	Default headers to include in every request made by the client.

`baseURL`

The baseURL defines the destination for proper request routing. This is particularly useful when the server is hosted or mounted on a different origin than the client.

The baseURL option accepts only the protocol and origin. Any path components are ignored. To append a path, use the basePath configuration option instead.

@/client

import { createClient } from "@aura-stack/router/client"

export const client = createClient({
  baseURL: "http://localhost:3000",
})

`basePath`

The basePath option allows a path prefix to be automatically prepended to all requests made by the client.

@/client

import { createClient } from "@aura-stack/router/client"

export const client = createClient({
  baseURL: "http://localhost:3000",
  basePath: "/api/v1",
})

`headers`

The headers option specifies default headers to include in every request. These headers are merged with any headers defined in individual client calls.

@/client

import { createClient } from "@aura-stack/router/client"

export const client = createClient({
  baseURL: "http://localhost:3000",
  headers: {
    accept: "application/json",
    "content-type": "application/json",
    "cache-control": "no-store",
    pragma: "no-cache",
  },
})

Returns

The createClient function returns a typed object containing only the HTTP methods defined by the router's endpoints. It also enforces the structure of required arguments based on Zod schemas. This design ensures that developers access only valid handler methods and prevents runtime errors through TypeScript's static type system.

Return	Type	Description
client	`Client<InferEndpoints<InferRouter>>`	An object containing only the HTTP methods defined in the endpoints of the provided router.

This return type guarantees full type safety. If an endpoint does not define a DELETE method, TypeScript prevents access to DELETE on the router.

`client`

The returned client object exposes only the HTTP methods corresponding to the endpoints defined in the router, ensuring type safety.

Type-Safe Handler Access: If the router does not define a particular route (e.g., DELETE), TypeScript restricts access to it.
Endpoint Route Safety: Ensures validation for routes defined per HTTP method.
Input Validation Safety: Enforces types for expected values, including those defined by Zod schemas and dynamic parameters.

@/client

import { createClient } from "@aura-stack/router/client"
import { router } from "@/index.ts"

export const client = createClient<typeof router>({
  baseURL: "http://localhost:3000",
})

// GET request to /users
client.get("/users")

// GET request to /users/:userId
client.get("/users/:userId", {
  params: {
    userId: 1,
  },
})

Usage

Basic Usage

@/client

import { router } from "@/index"
import { createClient } from "@aura-stack/router/client"

export const client = createClient<typeof router>({
  baseURL: "http://localhost:3000",
})

// GET request to http://localhost:3000/users
client.get("/users")

With `basePath`

@/client

import { router } from "@/index"
import { createClient } from "@aura-stack/router/client"

export const client = createClient<typeof router>({
  baseURL: "http://localhost:3000",
  basePath: "/api/v1",
})

// GET request to http://localhost:3000/api/v1/users
client.get("/users")

With `headers`

@/client

import { router } from "@/index"
import { createClient } from "@aura-stack/router/client"

export const client = createClient<typeof router>({
  baseURL: "http://localhost:3000",
  headers: {
    accept: "application/json",
    "content-type": "application/json",
    "cache-control": "no-store",
    pragma: "no-cache",
  },
})

// GET request to http://localhost:3000/users
// Headers included:
// Accept: application/json
// Content-Type: application/json
// Cache-Control: no-store
// Pragma: no-cache
client.get("/users")

On this page