Skip to main content

Configuration

Learn how to configure your Balda.js server with various options and plugins.

Server Configuration​

The Server constructor accepts a configuration object with the following options:

import { Server } from 'balda-js';

const server = new Server({
  port: 3000,                    // Server port (default: 80)
  host: '0.0.0.0',             // Server host (default: '0.0.0.0')
  controllerPatterns: [          // Controller file patterns
    './controllers/**/*.ts'
  ],
  plugins: {                     // Global Plugin configuration
    cors: { origin: '*' },
    json: { sizeLimit: '1mb' }
  },
  swagger: true,                 // Enable Swagger docs (default: true)
  tapOptions: {}                 // Runtime-specific options applied before start
});

Plugin Configuration​

CORS Plugin​

Configure Cross-Origin Resource Sharing:

plugins: {
  cors: {
    origin: ['http://localhost:3000', 'https://myapp.com'],
    methods: ['GET', 'POST', 'PUT', 'DELETE'],
    allowedHeaders: ['Content-Type', 'Authorization'],
    credentials: true
  }
}

JSON Plugin​

Configure JSON body parsing:

plugins: {
  json: {
    sizeLimit: '10mb',           // Maximum request body size
    strict: true,                // Strict JSON parsing
    type: 'application/json'     // Content type to parse
  }
}

Static Files Plugin​

Serve static files:

plugins: {
  static: {
    root: './public',            // Static files directory
    prefix: '/static',           // URL prefix (optional)
    index: 'index.html'          // Default index file
  }
}

Configure cookie parsing:

plugins: {
  cookie: {
    secret: 'your-secret-key',   // Secret for signed cookies
    secure: false,               // HTTPS only (production: true)
    httpOnly: true,              // Prevent XSS attacks
    sameSite: 'Strict'           // CSRF protection
  }
}

Helmet Plugin​

Configure security headers:

plugins: {
  helmet: {
    contentSecurityPolicy: {
      directives: {
        defaultSrc: ["'self'"],
        styleSrc: ["'self'", "'unsafe-inline'"],
        scriptSrc: ["'self'"]
      }
    },
    hsts: {
      maxAge: 31536000,
      includeSubDomains: true
    }
  }
}

Rate Limiter Plugin​

Configure request rate limiting:

plugins: {
  rateLimiter: {
    windowMs: 15 * 60 * 1000,    // 15 minutes
    max: 100,                    // Limit each IP to 100 requests per window
    message: 'Too many requests',
    standardHeaders: true,
    legacyHeaders: false
  }
}

Log Plugin​

Configure request/response logging:

plugins: {
  log: {
    logRequest: true,            // Log incoming requests
    logResponse: true,           // Log responses
    logError: true,              // Log errors
    format: 'combined'           // Log format
  }
}

File Upload Plugin​

Configure file upload handling:

plugins: {
  file: {
    maxFileSize: '10mb',         // Maximum file size
  }
}

URL Encoded Plugin​

Configure www-urlencoded data parsing:

plugins: {
  urlencoded: {
    extended: true,              // Use qs library for parsing
    limit: '10mb',               // Maximum body size
    parameterLimit: 1000         // Maximum parameters
  }
}