`createEndpointConfig`

The createEndpointConfig function is a declarative API used to define optional configuration for endpoints created with createEndpoint. It provides strong type inference for schemas, context, and middlewares.

import { z } from "zod"
import { createEndpointConfig } from "@aura-stack/router"

const config = createEndpointConfig({
  schemas: {
    body: z.object({
      username: z.string(),
      password: z.string(),
    }),
  },
})

This function improves type inference at build time and does not perform runtime validation.

Overview

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

Key Concepts
Type Inference
API Reference
- Parameters
- Overloads
Usage Examples

Key Concepts

createEndpointConfig enables full type inference for the endpoint context, schemas, and middlewares.
The function provides two overloads:
- Overload 1: Configuration object only — used when the endpoint does not rely on dynamic route parameters.
- Overload 2: Route pattern + configuration object — used when typed dynamic parameters are required within middlewares.

Type Inference

Configurations created through createEndpointConfig provide more accurate type inference than passing the configuration inline to createEndpoint. While implicit inference is recommended, explicit types can still be imported if stricter definitions are required.

Types can be accessed from the main entry points / or /types.

Example: Inferred Context with Schemas

import { z } from "zod"
import { createEndpointConfig } from "@aura-stack/router"

const config = createEndpointConfig({
  schemas: {
    searchParams: z.object({
      redirect_uri: z.string(),
      code: z.string(),
      state: z.string(),
    }),
  },
  use: [
    async (ctx) => {
      const { redirect_uri, code, state } = ctx.searchParams
      return ctx
    },
  ],
})

Example: Inferred Dynamic Params with Explicit Route

import { z } from "zod"
import { createEndpointConfig } from "@aura-stack/router"

const config = createEndpointConfig("/auth/signIn/:oauth/", {
  schemas: {
    searchParams: z.object({
      redirect_uri: z.string(),
      code: z.string(),
      state: z.string(),
    }),
  },
  use: [
    async (ctx) => {
      const { oauth } = ctx.params
      const { redirect_uri, code, state } = ctx.searchParams
      return ctx
    },
  ],
})

API Reference

Parameters

The createEndpointConfig function accepts parameters based on the chosen overload.

function createEndpointConfig<Schemas extends EndpointSchemas>(
  config: EndpointConfig<RoutePattern, Schemas>
): EndpointConfig<RoutePattern, Schemas>

function createEndpointConfig<Route extends RoutePattern, Schemas extends EndpointSchemas>(
  route: Route,
  config: EndpointConfig<Route, Schemas>
): EndpointConfig<Route, Schemas>

Parameter	Type	Description
`route`	`RoutePattern`	Optional. Defines the route pattern and enables inference for dynamic route parameters.
`config`	`EndpointSchemas`	Configuration object containing Zod schemas and middleware declarations for the endpoint.

`route`

The route parameter allows providing a route pattern. Supplying a route pattern enables type inference for dynamic parameters declared in that route.

import type { RoutePattern } from "@aura-stack/router/types"

// Expected: `/${string}`
type Route = RoutePattern

When a dynamic route pattern is provided, the function uses its segments to infer the shape of ctx.params.

import { createEndpointConfig } from "@aura-stack/router"

const config = createEndpointConfig("/auth/signIn/:oauth", {})

`config`

The config parameter allows defining optional Zod schemas for request params, searchParams, and body, as well as middleware functions. Schemas enhance type inference and add optional runtime validation.

import { z } from "zod"
import { createEndpointConfig } from "@aura-stack/router"

const config = createEndpointConfig("/auth/signIn/:oauth", {
  schemas: {
    params: z.object({
      oauth: z.enum(["github", "google"]),
    }),
  },
})

Usage

With Basic Overload

The basic overload is used when the endpoint does not define dynamic route parameters.

import type { EndpointSchemas, EndpointConfig } from "@aura-stack/router/types"

function createEndpointConfig<Schemas extends EndpointSchemas>(
  config: EndpointConfig<RoutePattern, Schemas>
): EndpointConfig<RoutePattern, Schemas>

Example:

import { z } from "zod"
import { createEndpointConfig } from "@aura-stack/router"

const config = createEndpointConfig({
  schemas: {
    body: z.object({
      username: z.string(),
      password: z.string(),
    }),
  },
})

With Dynamic Overload

This overload matches when the endpoint includes dynamic route parameters, enabling full type inference for ctx.params.

import { z } from "zod"
import { createEndpointConfig } from "@aura-stack/router"

const config = createEndpointConfig("/auth/signIn/:oauth/", {
  schemas: {
    searchParams: z.object({
      redirect_uri: z.string(),
      code: z.string(),
      state: z.string(),
    }),
  },
})

On this page