What is `@aura-stack/router`

Welcome to @aura-stack/router package. It is a modern, TypeScript-first router and endpoint definition library for TypeScript backends that provides supported for Next.js, Nuxt, Sveltekit and more. Build fully-typed APIs with declarative endpoints, automatic parameter inference, and first-class middleware support — all returning native Response objects for seamless compatibility with the Fetch API and modern API to be supported by the major of professional TypeScript applications.

All of the package is built-in in TypeScript providing a strong type-safe and type-inference for a better experience coding.

What you'll learn

Through this quick start guide you are going to learn and understand the basics of how to create a endpoint definitions

Getting Started
Installation
Endpoint Definitions
Router

Getting Started

This guide walks you through installation, setup, and the fundamental building blocks you need to create type-safe endpoints and routers in your TypeScript project.

Installation

Install the package and its peer dependency:

npm install @aura-stack/router zod

zod is an optional peer dependency used for schema validation via createEndpoint and createEndpointConfig. Install it if you plan to use schema-based validation.

Endpoints

Endpoints are the foundation of your API. Each endpoint maps an HTTP method and route to a handler function.

Creating Endpoints

Use createEndpoint to define an endpoint. It requires three arguments:

HTTPMethod: The HTTP method for the endpoint.
Route: The route pattern.
Route Handler: The function that executes when the route is matched.

@/users.ts

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

const getUsers = createEndpoint("GET", "/users", async (ctx) => {
  return Response.json({ users: [] })
})

const getUser = createEndpoint("GET", "/users/:userId", async (ctx) => {
  const { userId } = ctx.params
  return Response.json({ id: userId, name: "John" })
})

Router

Routers group multiple endpoints and generate type-safe HTTP handlers for your runtime.

Creating a Router

Use createRouter to combine endpoint definitions:

@/routes.ts

import { createRouter } from "@aura-stack/router"
import { getUser, getUsers } from "@/users.ts"

export const router = createRouter([getUser, getUsers])

Router Configuration

Base Path

Add a prefix to all routes in the router using basePath:

@/routes.ts

import { createRouter } from "@aura-stack/router"
import { getUser, getUsers } from "@/users.ts"

export const router = createRouter([getUser, getUsers], {
  basePath: "/api/v1",
})

Global Middlewares

Use middlewares to register logic that should run before every endpoint:

@/routes.ts

import { createRouter } from "@aura-stack/router"
import { getUser, getUsers } from "@/users.ts"

export const router = createRouter([getUser, getUsers], {
  middlewares: [],
})

Catching Errors

Use onError to catch and customize unexpected errors:

Internal router errors.
Handler exceptions.
Middleware errors.

@/routes.ts

import { createRouter } from "@aura-stack/router"
import { getUser, getUsers } from "@/users.ts"

export const router = createRouter([getUser, getUsers], {
  onError: (error, request) => {
    return Response.json({ message: "Unexpected Error" })
  },
})

Get HTTP handlers

Once your router is defined, you can export the generated handlers for use in any Fetch-compatible runtime:

@/main.ts

import { router } from "@/routes.ts"

export const { GET } = router

On this page