Middleware

Middleware in Shapeless lets you add reusable logic that runs between procedure calls and handlers. It’s ideal for cross-cutting concerns like authentication, logging, and error handling.

Basic Middleware Structure

// resources/shapeless.ts
const myMiddleware = app.middleware(async ({ c, next }) => {
  // 1️⃣ Code that runs before the handler
  // ...

  // 2️⃣ Pass data to the next middleware or handler
  return await next({ customData: "value" })
})

Common Use Cases

Authentication Middleware

This middleware ensures the user is authenticated before proceeding. If not authenticated, it throws an error and blocks the procedure:

// resources/shapeless.ts
import { HTTPException } from "hono/http-exception"
import { shapeless } from "@shapelesss/core"

interface Env {
  Bindings: { DATABASE_URL: string }
}

export const app = shapeless.init<Env>()

const authMiddleware = app.middleware(async ({ c, next }) => {
  // Mock authentication check
  const isAuthenticated = true

  if (!isAuthenticated) {
    throw new HTTPException(401, {
      message: "Unauthorized, please sign in.",
    })
  }

  // Attach user info to context for downstream handlers
  return await next({ user: { name: "John Doe" } })
})

export const publicProcedure = app.procedure
export const privateProcedure = publicProcedure.use(authMiddleware)

Now, in any privateProcedure, you can safely access the user info:

// resources/routers/post-router.ts
import { app, privateProcedure } from "../shapeless"

export const postRouter = app.router({
  list: privateProcedure.get(({ c, ctx }) => {
    // Access user info injected by middleware
    const { user } = ctx

    return c.json({ posts: [] })
  }),
})

Middleware Chaining

You can chain multiple middlewares using .use():

const enhancedProcedure = publicProcedure
  .use(authMiddleware)
  .use(loggingMiddleware)
  .use(rateLimitMiddleware)

If middleware depends on previous middleware outputs, use Shapeless’s type inference utility to type ctx correctly:

// resources/shapeless.ts
import { InferMiddlewareOutput, shapeless } from "@shapelesss/core"

interface Env {
  Bindings: { DATABASE_URL: string }
}

export const app = shapeless.init<Env>()

const authMiddleware = app.middleware(async ({ c, next }) => {
  return await next({ user: { name: "John Doe" } })
})

type AuthOutput = InferMiddlewareOutput<typeof authMiddleware>

const loggingMiddleware = app.middleware(async ({ c, ctx, next }) => {
  const { user } = ctx as AuthOutput

  const start = performance.now()
  await next()
  const end = performance.now()

  console.log(`${user.name}'s request took ${end - start}ms`)
})

export const publicProcedure = app.procedure
export const privateProcedure = publicProcedure
  .use(authMiddleware)
  .use(loggingMiddleware)

Using Hono Middleware

Shapeless is compatible with Hono middleware using the fromHono adapter:

import { app } from "../shapeless"
import { cors } from "hono/cors"

const corsMiddleware = app.fromHono(cors())
const procedureWithCors = publicProcedure.use(corsMiddleware)

Best Practices

Keep middleware focused on a single responsibility.
Handle errors globally with your appRouter's onError() method.

Common Middleware Examples

Authentication
Request logging
Rate limiting
Error handling
Input validation
Performance monitoring
CORS handling

→ See all built-in Hono middleware in the Hono docs.

Middleware

On this page