Installation

Install the Package

Aura Router package are distributed via npmjs, jsr.io and jsDelivr registries. You could install the package in any JavaScript project.

npm install @aura-stack/router

To enable end-to-end type safety and validation, install your preferred schema validation library. Aura Router supports Zod, TypeBox, Valibot, and ArkType.

npm install zod

npm install typebox

npm install valibot

npm install arktype

Define Endpoints

Endpoints are the fundamental building blocks of Aura Router, defining the route path, HTTP method, and execution logic. You can create endpoints using the createEndpoint function.

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

const signIn = createEndpoint(
  "POST",
  "/sign-in",
  async (ctx) => {
    const { username, password } = ctx.body
    if (username !== "admin" || password !== "password") {
      return ctx.json({ authenticated: false }, { status: 401 })
    }
    return ctx.json({ authenticated: true })
  },
  signInConfig
)

Adding Schema Validation

You can couple runtime validation and type inference to your endpoints using createEndpointConfig. Request fields (headers, params, searchParams, and body) are fully validated against your schema before execution.

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

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

import * as typebox from "typebox"
import { createEndpointConfig } from "@aura-stack/router/endpoint"

export const signInConfig = createEndpointConfig({
  schemas: {
    body: typebox.Object({
      username: typebox.String(),
      password: typebox.String(),
    }),
  },
})

import * as typebox from "valibot"
import { createEndpointConfig } from "@aura-stack/router/endpoint"

export const signInConfig = createEndpointConfig({
  schemas: {
    body: valibot.object({
      username: valibot.string(),
      password: valibot.string(),
    }),
  },
})

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

export const signInConfig = createEndpointConfig({
  schemas: {
    body: type({
      username: "string",
      password: "string",
    }),
  },
})

Assemble the Router

Group your defined endpoints together using createRouter. This generates a type-safe router structure ready to handle incoming requests for your runtime.

import { createRouter } from "@aura-stack/router"
import { signIn } from "@/api/endpoints.ts"

export const router = createRouter([signIn])
export type Router = typeof router

Create the Type-Safe Client API

Generate a fully typed client to interact with your router seamlessly across frontend applications or microservices. The client automatically infers parameters, request bodies, headers, and response types directly from your router type definition.

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

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