Home

Configuration

Customize Kempo Server's behavior with a simple JSON configuration file.

Configuration File

Important: The configuration file must be placed inside the server root directory (the folder specified by --root). For example, if you run kempo-server --root public, your config file should be at public/.config.json or public/dev.config.json, not in the project root.

To configure the server, create a configuration file (by default .config.json) within the root directory of your server (public in the start example). You can specify a different configuration file using the --config flag:

# Use default .config.json
kempo-server --root public

# Use custom config file
kempo-server --root public --config staging.config.json

# Use absolute path
kempo-server --root public --config /etc/kempo/production.config.json

This json file can have any of the following properties. Any property not defined will use the default configuration.

Configuration Options

allowedMimes - File types that can be served
disallowedRegex - Patterns for paths that should be blocked
customRoutes - Custom route mappings
routeFiles - Files that should be treated as route handlers
noRescanPaths - Paths that should not trigger file system rescans
maxRescanAttempts - Maximum number of rescan attempts
maxBodySize - Maximum request body size in bytes
cache - Module caching configuration
middleware - Middleware configuration

allowedMimes

An object mapping file extensions to their MIME types and encoding. Each value is an object with mime and encoding properties. Files with extensions not in this list will not be served.

{
  "allowedMimes": {
    "html": { "mime": "text/html", "encoding": "utf8" },
    "css": { "mime": "text/css", "encoding": "utf8" },
    "js": { "mime": "application/javascript", "encoding": "utf8" },
    "json": { "mime": "application/json", "encoding": "utf8" },
    "png": { "mime": "image/png", "encoding": "binary" },
    "jpg": { "mime": "image/jpeg", "encoding": "binary" },
    "jpeg": { "mime": "image/jpeg", "encoding": "binary" },
    "gif": { "mime": "image/gif", "encoding": "binary" },
    "svg": { "mime": "image/svg+xml", "encoding": "utf8" },
    "woff": { "mime": "font/woff", "encoding": "binary" },
    "woff2": { "mime": "font/woff2", "encoding": "binary" }
  }
}

disallowedRegex

An array of regular expressions that match paths that should never be served. This provides security by preventing access to sensitive files.

{
  "disallowedRegex": [
    "^/\\..*",        // Hidden files (starting with .)
    "\\.env$",        // Environment files
    "\\.config$",     // Configuration files
    "password",      // Files containing "password"
    "node_modules",  // Node modules directory
    "\\.git"          // Git directory
  ]
}

routeFiles

An array of filenames that should be treated as route handlers and executed as JavaScript modules.

{
  "routeFiles": [
    "GET.js",
    "POST.js",
    "PUT.js",
    "DELETE.js",
    "PATCH.js",
    "HEAD.js",
    "OPTIONS.js",
    "index.js"
  ]
}

noRescanPaths

An array of regex patterns for paths that should not trigger a file system rescan. This improves performance for common static assets.

{
  "noRescanPaths": [
    "/favicon\\.ico$",
    "/robots\\.txt$",
    "\\.map$",
    "\\.css$",
    "\\.js$",
    "\\.png$",
    "\\.jpg$",
    "\\.jpeg$",
    "\\.gif$"
  ]
}

customRoutes

An object mapping custom route paths to file paths. Useful for aliasing or serving files from outside the document root.

Path Resolution: All paths in customRoutes are resolved relative to the config file's location (which is the server root). To reference files outside the server root (like node_modules or a src folder), use ../ to navigate up to the project root.

Route Priority: Custom routes take priority over files that exist in the directory structure. If you have both public/dist/app.js and a custom route "/dist/**": "../src/**", the custom route will be used and the file will be served from src/.

Basic Routes

Map specific paths to files:

{
  "customRoutes": {
    "/vendor/bootstrap.css": "./node_modules/bootstrap/dist/css/bootstrap.min.css",
    "/api/status": "./status.js",
    "/health": "./health-check.js"
  }
}

Wildcard Routes

Wildcard routes allow you to map entire directory structures using the * wildcard:

{
  "customRoutes": {
    "kempo/*": "./node_modules/kempo/dist/*",
    "assets/*": "./static-files/*",
    "docs/*": "./documentation/*",
    "lib/*": "./node_modules/my-library/build/*"
  }
}

With wildcard routes:

kempo/styles.css would serve ./node_modules/kempo/dist/styles.css
assets/logo.png would serve ./static-files/logo.png
docs/readme.md would serve ./documentation/readme.md
lib/utils.js would serve ./node_modules/my-library/build/utils.js

Wildcard Syntax

* - Matches a single path segment (anything between / characters)
** - Matches recursively (any depth of subdirectories)

Use ** when you want to redirect an entire directory tree. Multiple wildcards can be used in a single route pattern.

Common Use Case: Dev vs Production Builds

A common pattern is to serve source files during development but built/minified files in production. Given this project structure:

project/
├── src/                    # Source files
│   └── app.js
├── node_modules/
├── public/                 # Server root (--root public)
│   ├── dev.config.json     # Config lives HERE (inside server root)
│   ├── dist/               # Built files
│   │   └── app.js
│   └── index.html

Your dev.config.json can redirect /dist/** requests to serve from src/ instead:

{
  "customRoutes": {
    "/dist/**": "../src/**",
    "/kempo-ui/**": "../node_modules/kempo-ui/**"
  }
}

Now requests to /dist/app.js will serve ../src/app.js (the unminified source), while production uses the actual dist/ files.

maxRescanAttempts

The maximum number of times to attempt rescanning the file system when a file is not found. Defaults to 3.

{
  "maxRescanAttempts": 3
}

maxBodySize

Maximum allowed request body size in bytes. If a request body exceeds this limit, the server responds with 413 Payload Too Large before the route handler runs. Defaults to 1048576 (1 MB).

{
  "maxBodySize": 1048576
}

middleware

Configuration for built-in and custom middleware. Middleware runs before your route handlers and can modify requests, responses, or handle requests entirely.

{
  "middleware": {
    "cors": {
      "enabled": true,
      "origin": "*"
    },
    "compression": {
      "enabled": true
    },
    "custom": ["./middleware/auth.js"]
  }
}

Complete Configuration Example

Here's a complete example of a .config.json file:

{
  "allowedMimes": {
    "html": "text/html",
    "css": "text/css",
    "js": "application/javascript",
    "json": "application/json",
    "png": "image/png",
    "jpg": "image/jpeg",
    "jpeg": "image/jpeg",
    "gif": "image/gif",
    "svg": "image/svg+xml",
    "woff": "font/woff",
    "woff2": "font/woff2"
  },
  "disallowedRegex": [
    "^/\\..*",
    "\\.env$",
    "\\.config$",
    "password",
    "node_modules",
    "\\.git"
  ],
  "routeFiles": [
    "GET.js",
    "POST.js",
    "PUT.js",
    "DELETE.js",
    "PATCH.js",
    "HEAD.js",
    "OPTIONS.js",
    "index.js"
  ],
  "noRescanPaths": [
    "/favicon\\.ico$",
    "/robots\\.txt$",
    "\\.map$",
    "\\.css$",
    "\\.js$",
    "\\.png$",
    "\\.jpg$",
    "\\.jpeg$",
    "\\.gif$"
  ],
  "customRoutes": {
    "/vendor/bootstrap.css": "./node_modules/bootstrap/dist/css/bootstrap.min.css",
    "/vendor/jquery.js": "./node_modules/jquery/dist/jquery.min.js",
    "assets/*": "./static-files/*",
    "docs/*": "./documentation/*"
  },
  "maxRescanAttempts": 3,
  "middleware": {
    "cors": {
      "enabled": true,
      "origin": "*",
      "methods": ["GET", "POST", "PUT", "DELETE"],
      "headers": ["Content-Type", "Authorization"]
    },
    "compression": {
      "enabled": true,
      "threshold": 1024
    },
    "security": {
      "enabled": true,
      "headers": {
        "X-Content-Type-Options": "nosniff",
        "X-Frame-Options": "DENY",
        "X-XSS-Protection": "1; mode=block"
      }
    },
    "custom": [
      "./middleware/auth.js",
      "./middleware/logging.js"
    ]
  }
}

Environment-Specific Configuration

You can create different configuration files for different environments and specify them using the --config flag:

Development Configuration

Create .config.dev.json for development:

{
  "allowedMimes": {
    "html": "text/html",
    "css": "text/css",
    "js": "application/javascript",
    "json": "application/json",
    "map": "application/json"
  },
  "middleware": {
    "cors": {
      "enabled": true,
      "origin": "*"
    },
    "compression": {
      "enabled": false
    }
  }
}

{
  "allowedMimes": {
    "html": { "mime": "text/html", "encoding": "utf8" },
    "css": { "mime": "text/css", "encoding": "utf8" },
    "js": { "mime": "application/javascript", "encoding": "utf8" },
    "json": { "mime": "application/json", "encoding": "utf8" },
    "map": { "mime": "application/json", "encoding": "utf8" }
  },
  "middleware": {
    "cors": {
      "enabled": true,
      "origin": "*"
    },
    "compression": {
      "enabled": false
    }
  }
}

{
  "allowedMimes": {
    "html": { "mime": "text/html", "encoding": "utf8" },
    "css": { "mime": "text/css", "encoding": "utf8" },
    "js": { "mime": "application/javascript", "encoding": "utf8" },
    "json": { "mime": "application/json", "encoding": "utf8" },
    "png": { "mime": "image/png", "encoding": "binary" },
    "jpg": { "mime": "image/jpeg", "encoding": "binary" }
  },
  "disallowedRegex": [
    "^/\\..*",
    "\\.env$",
    "\\.config$",
    "password",
    "node_modules",
    "\\.git",
    "\\.map$"
  ],
  "middleware": {
    "cors": {
      "enabled": true,
      "origin": "https://yourdomain.com"
    },
    "compression": {
      "enabled": true,
      "threshold": 1024
    },
    "security": {
      "enabled": true,
      "headers": {
        "X-Content-Type-Options": "nosniff",
        "X-Frame-Options": "DENY",
        "X-XSS-Protection": "1; mode=block",
        "Strict-Transport-Security": "max-age=31536000; includeSubDomains"
      }
    }
  }
}

Use with: kempo-server --root public --config .config.dev.json

Production Configuration

Create .config.prod.json for production:

{
  "allowedMimes": {
    "html": "text/html",
    "css": "text/css",
    "js": "application/javascript",
    "json": "application/json",
    "png": "image/png",
    "jpg": "image/jpeg"
  },
  "disallowedRegex": [
    "^/\\..*",
    "\\.env$",
    "\\.config$",
    "password",
    "node_modules",
    "\\.git",
    "\\.map$"
  ],
  "middleware": {
    "cors": {
      "enabled": true,
      "origin": "https://yourdomain.com"
    },
    "compression": {
      "enabled": true,
      "threshold": 1024
    },
    "security": {
      "enabled": true,
      "headers": {
        "X-Content-Type-Options": "nosniff",
        "X-Frame-Options": "DENY",
        "X-XSS-Protection": "1; mode=block",
        "Strict-Transport-Security": "max-age=31536000; includeSubDomains"
      }
    }
  }
}

Use with: kempo-server --root public --config .config.prod.json

cache

Module caching configuration to improve performance by keeping compiled JavaScript modules in memory. The cache supports LRU eviction, TTL expiration, memory monitoring, and automatic file watching.

{
  "cache": {
    "enabled": true,
    "maxSize": 1000,
    "ttlMs": 3600000,
    "maxMemoryUsageMB": 500,
    "checkIntervalMs": 30000,
    "fileWatching": true
  }
}

Cache Configuration Options

Option	Type	Default	Description
`enabled`	boolean	true	Enable/disable module caching system
`maxSize`	number	1000	Maximum number of modules to cache (LRU eviction)
`ttlMs`	number	3600000	Time-to-live in milliseconds (default: 1 hour)
`maxMemoryUsageMB`	number	500	Maximum memory usage in MB before triggering cleanup
`checkIntervalMs`	number	30000	Memory check interval in milliseconds (default: 30 seconds)
`fileWatching`	boolean	true	Watch files for changes and auto-invalidate cache

Environment-Specific Cache Settings

Development (.config.dev.json)

{
  "cache": {
    "enabled": true,
    "maxSize": 100,
    "ttlMs": 300000,
    "fileWatching": true
  }
}

Production (.config.prod.json)

{
  "cache": {
    "enabled": true,
    "maxSize": 5000,
    "ttlMs": 7200000,
    "maxMemoryUsageMB": 1000,
    "fileWatching": false
  }
}

Cache Monitoring

Access cache statistics and management via admin endpoints:

GET /_admin/cache - View cache statistics (hits, misses, size, memory usage)
DELETE /_admin/cache - Clear all cached modules

For detailed cache usage and configuration examples, see the Caching Guide.

Package.json Scripts

Add environment-specific scripts to your package.json:

{
  "scripts": {
    "start": "kempo-server --root public",
    "start:dev": "kempo-server --root public --config .config.dev.json --verbose",
    "start:staging": "kempo-server --root public --config .config.staging.json",
    "start:prod": "kempo-server --root public --config .config.prod.json"
  }
}

Configuration Tips

Security Best Practices

Always include patterns to block sensitive files in disallowedRegex
Use strict CORS settings in production
Enable security headers middleware
Don't serve source maps in production

Performance Optimization

Enable module caching with appropriate maxSize and ttlMs settings
Use noRescanPaths for static assets to improve performance
Enable compression for larger files
Use custom routes to serve files from CDN or optimized locations
Limit maxRescanAttempts to prevent excessive file system scanning
Configure maxMemoryUsageMB to prevent memory issues in production

Development vs Production

Enable source maps in development, disable in production
Use relaxed CORS in development, strict in production
Enable compression in production for better performance
Add more security headers in production
Use smaller cache sizes in development, larger in production
Enable file watching in development, disable in production for stability
Use shorter TTL in development for faster iteration