kempo-server 2.2.0 → 3.0.1

package/CONFIG.md

@@ -1,6 +1,6 @@
 # Configuration
 
-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.
+To configure the server, create a configuration file (by default `.config.js`) within the root directory of your server (`public` in the start example). The server also supports `.config.json` as a fallback. You can specify a different configuration file using the `--config` flag.
 
 **Important:** 
 - When using a relative path for the `--config` flag, the config file must be located within the server root directory
@@ -13,21 +13,31 @@ You can specify different configuration files for different environments using t
 
 ```bash
 # Development
-kempo-server --root public --config dev.config.json
+kempo-server --root public --config dev.config.js
 
 # Staging
-kempo-server --root public --config staging.config.json
+kempo-server --root public --config staging.config.js
 
 # Production with absolute path
-kempo-server --root public --config /etc/kempo/production.config.json
+kempo-server --root public --config /etc/kempo/production.config.js
 
 # Mix with other options
-kempo-server --root dist --port 8080 --config production.config.json
+kempo-server --root dist --port 8080 --config production.config.js
+
+# JSON config files are also supported
+kempo-server --root public --config legacy.config.json
 ```
 
 ## Configuration File Structure
 
-This json file can have any of the following properties, any property not defined will use the "Default Config".
+The config file exports a default object with any of the following properties. Any property not defined will use the "Default Config".
+
+```javascript
+// .config.js
+export default {
+  // your config here
+};
+```
 
 - [allowedMimes](#allowedmimes)
 - [disallowedRegex](#disallowedregex)
@@ -38,6 +48,7 @@ This json file can have any of the following properties, any property not define
 - [maxBodySize](#maxbodysize)
 - [cache](#cache)
 - [middleware](#middleware)
+- [templating](#templating)
 
 ## Cache
 
@@ -50,18 +61,18 @@ Kempo Server includes an intelligent module caching system that dramatically imp
 
 ### Basic Cache Configuration
 
-Enable caching in your `.config.json`:
+Enable caching in your `.config.js`:
 
-```json
-{
-  "cache": {
-    "enabled": true,
-    "maxSize": 100,
-    "maxMemoryMB": 50,
-    "ttlMs": 300000,
-    "watchFiles": true
+```javascript
+export default {
+  cache: {
+    enabled: true,
+    maxSize: 100,
+    maxMemoryMB: 50,
+    ttlMs: 300000,
+    watchFiles: true
   }
-}
+};
 ```
 
 ### Cache Options
@@ -75,7 +86,7 @@ Enable caching in your `.config.json`:
 - `watchFiles` (boolean) - Auto-invalidate on file changes (default: `true`)
 - `enableMemoryMonitoring` (boolean) - Enable memory monitoring (default: `true`)
 
-Run with specific config: `kempo-server --config prod.config.json`
+Run with specific config: `kempo-server --config prod.config.js`
 
 ### Cache Monitoring
 
@@ -105,92 +116,92 @@ Kempo Server includes a powerful middleware system that allows you to add functi
 #### CORS
 Enable Cross-Origin Resource Sharing for your API:
 
-```json
-{
-  "middleware": {
-    "cors": {
-      "enabled": true,
-      "origin": "*",
-      "methods": ["GET", "POST", "PUT", "DELETE"],
-      "headers": ["Content-Type", "Authorization"]
+```javascript
+export default {
+  middleware: {
+    cors: {
+      enabled: true,
+      origin: '*',
+      methods: ['GET', 'POST', 'PUT', 'DELETE'],
+      headers: ['Content-Type', 'Authorization']
     }
   }
-}
+};
 ```
 
 #### Compression
 Automatically compress responses with gzip:
 
-```json
-{
-  "middleware": {
-    "compression": {
-      "enabled": true,
-      "threshold": 1024
+```javascript
+export default {
+  middleware: {
+    compression: {
+      enabled: true,
+      threshold: 1024
     }
   }
-}
+};
 ```
 
 #### Rate Limiting
 Limit requests per client to prevent abuse:
 
-```json
-{
-  "middleware": {
-    "rateLimit": {
-      "enabled": true,
-      "maxRequests": 100,
-      "windowMs": 60000,
-      "message": "Too many requests"
+```javascript
+export default {
+  middleware: {
+    rateLimit: {
+      enabled: true,
+      maxRequests: 100,
+      windowMs: 60000,
+      message: 'Too many requests'
     }
   }
-}
+};
 ```
 
 #### Security Headers
 Add security headers to all responses:
 
-```json
-{
-  "middleware": {
-    "security": {
-      "enabled": true,
-      "headers": {
-        "X-Content-Type-Options": "nosniff",
-        "X-Frame-Options": "DENY",
-        "X-XSS-Protection": "1; mode=block"
+```javascript
+export default {
+  middleware: {
+    security: {
+      enabled: true,
+      headers: {
+        'X-Content-Type-Options': 'nosniff',
+        'X-Frame-Options': 'DENY',
+        'X-XSS-Protection': '1; mode=block'
       }
     }
   }
-}
+};
 ```
 
 #### Request Logging
 Log requests with configurable detail:
 
-```json
-{
-  "middleware": {
-    "logging": {
-      "enabled": true,
-      "includeUserAgent": true,
-      "includeResponseTime": true
+```javascript
+export default {
+  middleware: {
+    logging: {
+      enabled: true,
+      includeUserAgent: true,
+      includeResponseTime: true
     }
   }
-}
+};
 ```
 
 ### Custom Middleware
 
 Create your own middleware by writing JavaScript files and referencing them in your config:
 
-```json
-{
-  "middleware": {
-    "custom": ["./middleware/auth.js", "./middleware/analytics.js"]
+```javascript
+export default {
+  middleware: {
+    custom: ['./middleware/auth.js', './middleware/analytics.js']
   }
-}
+};
 ```
 
 #### Custom Middleware Example
@@ -284,62 +295,62 @@ export default (config) => {
 
 An object mapping file extensions to their MIME types. Files with extensions not in this list will not be served.
 
-```json
-{
-  "allowedMimes": {
-    "html": "text/html",
-    "css": "text/css",
-    "js": "application/javascript",
-    "json": "application/json",
-    "png": "image/png",
-    "jpg": "image/jpeg"
+```javascript
+export default {
+  allowedMimes: {
+    html: 'text/html',
+    css: 'text/css',
+    js: 'application/javascript',
+    json: 'application/json',
+    png: 'image/png',
+    jpg: 'image/jpeg'
   }
-}
+};
 ```
 
 ### disallowedRegex
 
 An array of regular expressions that match paths that should never be served. This provides security by preventing access to sensitive files.
 
-```json
-{
-  "disallowedRegex": [
-    "^/\\..*",
-    "\\.env$",
-    "\\.config$",
-    "password"
+```javascript
+export default {
+  disallowedRegex: [
+    '^/\\..*',
+    '\\.env$',
+    '\\.config$',
+    'password'
   ]
-}
+};
 ```
 
 ### routeFiles
 
 An array of filenames that should be treated as route handlers and executed as JavaScript modules.
 
-```json
-{
-  "routeFiles": [
-    "GET.js",
-    "POST.js",
-    "PUT.js",
-    "DELETE.js",
-    "index.js"
+```javascript
+export default {
+  routeFiles: [
+    'GET.js',
+    'POST.js',
+    'PUT.js',
+    'DELETE.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.
 
-```json
-{
-  "noRescanPaths": [
-    "/favicon\\.ico$",
-    "/robots\\.txt$",
-    "\\.map$"
+```javascript
+export default {
+  noRescanPaths: [
+    '/favicon\\.ico$',
+    '/robots\\.txt$',
+    '\\.map$'
   ]
-}
+};
 ```
 
 ### customRoutes
@@ -349,27 +360,27 @@ An object mapping custom route paths to file paths. Useful for aliasing or servi
 **Note:** All file paths in customRoutes are resolved relative to the server root directory (the `--root` path). This allows you to reference files both inside and outside the document root.
 
 **Basic Routes:**
-```json
-{
-  "customRoutes": {
-    "/vendor/bootstrap.css": "../node_modules/bootstrap/dist/css/bootstrap.min.css",
-    "/api/status": "./status.js"
+```javascript
+export default {
+  customRoutes: {
+    '/vendor/bootstrap.css': '../node_modules/bootstrap/dist/css/bootstrap.min.css',
+    '/api/status': './status.js'
   }
-}
+};
 ```
 
 **Wildcard Routes:**
 Wildcard routes allow you to map entire directory structures using the `*` and `**` wildcards:
 
-```json
-{
-  "customRoutes": {
-    "kempo/*": "../node_modules/kempo/dist/*",
-    "assets/*": "../static-files/*",
-    "docs/*": "../documentation/*",
-    "src/**": "../src/**"
+```javascript
+export default {
+  customRoutes: {
+    'kempo/*': '../node_modules/kempo/dist/*',
+    'assets/*': '../static-files/*',
+    'docs/*': '../documentation/*',
+    'src/**': '../src/**'
   }
-}
+};
 ```
 
 With wildcard routes:
@@ -398,123 +409,220 @@ If the resolved path is a file whose name matches `routeFiles` (e.g. `GET.js`),
 
 The maximum number of times to attempt rescanning the file system when a file is not found. Defaults to 3.
 
-```json
-{
-  "maxRescanAttempts": 3
-}
+```javascript
+export default {
+  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).
 
-```json
-{
-  "maxBodySize": 1048576
-}
+```javascript
+export default {
+  maxBodySize: 1048576
+};
 ```
 
+### templating
+
+The templating system lets you build HTML pages from reusable templates, fragments, and content blocks using valid XML syntax. Files use the conventions `*.template.html`, `*.page.html`, and `*.fragment.html`.
+
+```javascript
+export default {
+  templating: {
+    preRender: false,
+    ssr: false,
+    globals: {},
+    state: {},
+    maxFragmentDepth: 10
+  }
+};
+```
+
+- `preRender` (boolean) - Render all `.page.html` files to `.html` on server start (default: `false`)
+- `ssr` (boolean) - Render `.page.html` files on-the-fly when the corresponding `.html` file is not found (default: `false`)
+- `globals` (object) - Variables available in all templates. Values can be functions (called with no args at render time).
+- `state` (object) - Additional variables, typically CMS data. Merged after globals so state overrides globals.
+- `maxFragmentDepth` (number) - Maximum nesting depth for fragment includes (default: `10`)
+
+#### Pre-Render Mode
+
+With `preRender: true`, the server renders all page files when it starts or rescans. This is ideal for static sites.
+
+```javascript
+export default {
+  templating: {
+    preRender: true,
+    globals: {
+      siteName: 'My Site',
+      year: () => String(new Date().getFullYear())
+    }
+  }
+};
+```
+
+#### SSR Mode
+
+With `ssr: true`, when a request comes in for `/about` and `about.html` does not exist but `about.page.html` does, the server renders it on-the-fly.
+
+```javascript
+export default {
+  templating: {
+    ssr: true,
+    globals: {
+      siteName: 'My Site'
+    },
+    state: {
+      currentUser: 'Guest'
+    }
+  }
+};
+```
+
+#### CLI Rendering
+
+You can also render pages without starting the server using the CLI script:
+
+```bash
+kempo-render <inputDir> [outputDir] [stateFile]
+```
+
+The script loads `.config.js` (or `.config.json`) from the input directory for `templating.globals`, `templating.state`, and `templating.maxFragmentDepth`. An optional state file (`.js` or `.json`) merges additional state variables.
+
+#### Templating File Conventions
+
+- **Templates** (`*.template.html`): Layout files with `<location>` placeholders
+- **Pages** (`*.page.html`): Content files wrapped in `<page template="...">` with `<content location="...">` blocks
+- **Fragments** (`*.fragment.html`): Reusable HTML snippets included via `<fragment name="..." />`
+
+#### Built-in Variables
+
+These variables are available in all templates:
+- `{{pathToRoot}}` - Relative path to the root directory (e.g. `../../`)
+- `{{year}}` - Current four-digit year
+- `{{date}}` - Current date in ISO format (YYYY-MM-DD)
+- `{{datetime}}` - Full ISO datetime string
+- `{{timestamp}}` - Unix timestamp
+- `{{version}}` - Version from `package.json`
+- `{{env}}` - Value of `NODE_ENV`
+
+#### Conditionals and Loops
+
+```html
+<if condition="env === 'development'">
+  <p>Debug mode</p>
+</if>
+
+<foreach in="items" as="item">
+  <li>{{item.name}}</li>
+</foreach>
+```
+
+Conditions support `===`, `!==`, `>`, `<`, `>=`, `<=`, `&&`, `||`, `!`, parentheses, string/number/boolean literals, and dot-path variable references.
+
 ## Configuration Examples
 
 ### Development Environment
 
 **Focus: Fast iteration and debugging**
-```json
-{
-  "cache": {
-    "enabled": true,
-    "maxSize": 50,
-    "ttlMs": 300000,
-    "watchFiles": true
+```javascript
+export default {
+  cache: {
+    enabled: true,
+    maxSize: 50,
+    ttlMs: 300000,
+    watchFiles: true
   },
-  "middleware": {
-    "cors": {
-      "enabled": true,
-      "origin": "*"
+  middleware: {
+    cors: {
+      enabled: true,
+      origin: '*'
     },
-    "logging": {
-      "enabled": true,
-      "includeUserAgent": true,
-      "includeResponseTime": true
+    logging: {
+      enabled: true,
+      includeUserAgent: true,
+      includeResponseTime: true
     }
   }
-}
+};
 ```
 
 ### Production Environment
 
 **Focus: Performance, security, and stability**
-```json
-{
-  "cache": {
-    "enabled": true,
-    "maxSize": 1000,
-    "maxMemoryMB": 200,
-    "ttlMs": 3600000,
-    "maxHeapUsagePercent": 85,
-    "memoryCheckInterval": 60000,
-    "watchFiles": false
+```javascript
+export default {
+  cache: {
+    enabled: true,
+    maxSize: 1000,
+    maxMemoryMB: 200,
+    ttlMs: 3600000,
+    maxHeapUsagePercent: 85,
+    memoryCheckInterval: 60000,
+    watchFiles: false
   },
-  "middleware": {
-    "cors": {
-      "enabled": true,
-      "origin": ["https://myapp.com", "https://www.myapp.com"],
-      "credentials": true
+  middleware: {
+    cors: {
+      enabled: true,
+      origin: ['https://myapp.com', 'https://www.myapp.com'],
+      credentials: true
     },
-    "compression": {
-      "enabled": true,
-      "threshold": 1024
+    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"
+    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'
       }
     },
-    "logging": {
-      "enabled": true,
-      "includeUserAgent": false,
-      "includeResponseTime": true
+    logging: {
+      enabled: true,
+      includeUserAgent: false,
+      includeResponseTime: true
     }
   }
-}
+};
 ```
 
 ### Low-Memory Environment
 
 **Focus: Minimal resource usage**
-```json
-{
-  "cache": {
-    "enabled": true,
-    "maxSize": 20,
-    "maxMemoryMB": 5,
-    "ttlMs": 120000,
-    "maxHeapUsagePercent": 60,
-    "memoryCheckInterval": 10000
+```javascript
+export default {
+  cache: {
+    enabled: true,
+    maxSize: 20,
+    maxMemoryMB: 5,
+    ttlMs: 120000,
+    maxHeapUsagePercent: 60,
+    memoryCheckInterval: 10000
   }
-}
+};
 ```
 
 ### Debugging Environment
 
 **Focus: Cache disabled for troubleshooting**
-```json
-{
-  "cache": {
-    "enabled": false
+```javascript
+export default {
+  cache: {
+    enabled: false
   },
-  "middleware": {
-    "logging": {
-      "enabled": true,
-      "includeUserAgent": true,
-      "includeResponseTime": true
+  middleware: {
+    logging: {
+      enabled: true,
+      includeUserAgent: true,
+      includeResponseTime: true
     }
   }
-}
+};
 ```
 
 ## Additional Resources