Configuration

bun-router can be configured when initializing a new router instance. This page covers all the available configuration options.

Basic Configuration

When creating a new router instance, you can pass a configuration object:

import { Router } from 'bun-router'

const router = new Router({
  // Configuration options here
  verbose: true,
  apiPrefix: '/api',
})

Available Options

Here's a complete list of configuration options:

Option	Type	Default	Description
`verbose`	`boolean`	`false`	Enable verbose logging of routes and requests
`apiPrefix`	`string`	`''`	Global prefix for all routes
`baseUrl`	`string`	`''`	Base URL for generating route URLs
`defaultMiddleware`	`object`	`{}`	Default middleware to apply to routes
`corsOptions`	`object`	`null`	CORS configuration options
`serverErrorHandler`	`function`	`null`	Global error handler for server errors
`notFoundHandler`	`function`	`null`	Handler for 404 Not Found responses
`webSocketOptions`	`object`	`{}`	Default WebSocket configuration

Verbose Logging

When verbose is set to true, bun-router will log detailed information about route registration and request handling:

const router = new Router({
  verbose: true,
})

This is useful during development to debug routing issues.

API Prefix

The apiPrefix option adds a global prefix to all routes:

const router = new Router({
  apiPrefix: '/api/v1',
})

// This route will be accessible at /api/v1/users
router.get('/users', getUsersHandler)

Default Middleware

You can specify default middleware to be applied to different route types:

const router = new Router({
  defaultMiddleware: {
    api: [corsMiddleware, jsonBodyMiddleware],
    web: [sessionMiddleware, csrfMiddleware],
  },
})

CORS Configuration

Configure Cross-Origin Resource Sharing (CORS) globally:

const router = new Router({
  corsOptions: {
    origin: ['https://example.com'],
    methods: ['GET', 'POST'],
    allowHeaders: ['Content-Type', 'Authorization'],
    exposeHeaders: ['X-Custom-Header'],
    credentials: true,
    maxAge: 86400, // 24 hours
  },
})

Error Handlers

Customize how errors are handled:

const router = new Router({
  // Custom 500 error handler
  serverErrorHandler: (error) => {
    console.error('Server error:', error)
    return new Response('Something went wrong', { status: 500 })
  },

  // Custom 404 handler
  notFoundHandler: (req) => {
    return new Response(`Page not found: ${req.url}`, { status: 404 })
  },
})

WebSocket Configuration

Configure default WebSocket behavior:

const router = new Router({
  webSocketOptions: {
    maxPayloadLength: 32 * 1024 * 1024, // 32MB
    idleTimeout: 300, // 5 minutes
    backpressureLimit: 1024 * 1024, // 1MB
    perMessageDeflate: true,
    publishToSelf: false,
  },
})

Environment-Specific Configuration

You can create different configurations based on the environment:

const isDevelopment = process.env.NODE_ENV === 'development'

const router = new Router({
  verbose: isDevelopment,
  corsOptions: isDevelopment
    ? { origin: '*' }
    : { origin: ['https://myapp.com'] },
})

Per-Route Configuration

While global configuration is set on the router instance, many options can be overridden at the route level:

// Override CORS for a specific route
router.get('/public-api', handler, {
  cors: {
    origin: '*',
  },
})

// Override middleware for a route group
router.group({
  prefix: '/admin',
  middleware: [authMiddleware],
}, () => {
  // Routes in this group use authMiddleware
})