alepha@docs:~/docs/guides/server$
cat 7-middlewares.md
3 min read
Last commit:

#Middlewares

Alepha provides built-in middleware modules for common server needs.

#Built-in (AlephaServer)

The following are built into AlephaServer and active by default. Configure via atoms or disable globally.

#Compression

Response compression (gzip, brotli, zstd) based on the client's Accept-Encoding header. Active by default for JSON, HTML, JavaScript, CSS, and plain text responses.

Configure via the compressOptions atom:

typescript 
1import { compressOptions } from "alepha/server";2 3alepha.store.mut(compressOptions, (old) => ({4  ...old,5  disabled: true,  // disable compression entirely6}));
Option Default Description
disabled false Disable compression entirely
allowedContentTypes ["application/json", "text/html", "application/javascript", "text/plain", "text/css"] Content types eligible for compression

#Security Headers (Helmet)

HTTP security headers on every response. Active by default.

Configure via the helmetOptions atom:

typescript 
 1import { helmetOptions } from "alepha/server"; 2  3alepha.store.mut(helmetOptions, (old) => ({ 4  ...old, 5  xFrameOptions: "DENY", 6  contentSecurityPolicy: { 7    directives: { 8      defaultSrc: ["'self'"], 9      scriptSrc: ["'self'", "https://cdn.example.com"],10    },11  },12}));
Option Default Description
disabled false Disable security headers entirely
isSecure - Force secure context (HSTS)
strictTransportSecurity { maxAge: 15552000, includeSubDomains: true } HSTS configuration
xFrameOptions "SAMEORIGIN" X-Frame-Options header
xXssProtection false X-XSS-Protection header
referrerPolicy "strict-origin-when-cross-origin" Referrer-Policy header
contentSecurityPolicy - CSP directives

#Multipart

Multipart form-data parsing for file uploads. Active by default when a route schema includes t.file().

Configure via the multipartOptions atom:

typescript 
1import { multipartOptions } from "alepha/server";2 3alepha.store.mut(multipartOptions, (old) => ({4  ...old,5  limit: 50_000_000,      // 50MB total6  fileLimit: 10_000_000,  // 10MB per file7  fileCount: 20,8}));
Option Default Description
limit 10000000 (10MB) Maximum total multipart request size in bytes
fileLimit 5000000 (5MB) Maximum single file size in bytes
fileCount 10 Maximum number of files per request

#Optional Modules

These are registered with alepha.with().

#CORS

The $cors primitive configures Cross-Origin Resource Sharing. Import from alepha/server/cors.

typescript 
1import { $cors } from "alepha/server/cors";2 3class App {4  cors = $cors({5    origin: "https://app.example.com",6    credentials: true,7  });8}
Option Default Description
origin "*" Allowed origins. "*" for all, or comma-separated list.
methods ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"] Allowed HTTP methods
headers ["Content-Type", "Authorization"] Allowed request headers
credentials true Allow credentials (cookies, auth headers)
maxAge - Preflight cache duration in seconds
paths - Path patterns to match (e.g. ["/api/*"])

When paths is provided, the CORS configuration applies only to matching routes. Without paths, it applies globally.

Alepha automatically creates OPTIONS preflight routes for all non-GET routes when the CORS module is active.

#Rate Limiting

The $rateLimit primitive limits request rates per client. Import from alepha/server/rate-limit.

typescript 
1import { $rateLimit } from "alepha/server/rate-limit";2 3class App {4  limit = $rateLimit({5    max: 100,6    windowMs: 15 * 60 * 1000,  // 15 minutes7  });8}
Option Default Description
max 100 Maximum requests per window
windowMs 900000 (15 min) Window duration in milliseconds
paths - Path patterns to apply to
keyGenerator - Custom function to generate rate limit keys per request
skipFailedRequests false Do not count failed requests
skipSuccessfulRequests false Do not count successful requests

#Per-Action Rate Limiting

Apply rate limits directly on an action:

typescript 
 1import { $action } from "alepha/server"; 2  3class App { 4  login = $action({ 5    method: "POST", 6    path: "/auth/login", 7    rateLimit: { 8      max: 5, 9      windowMs: 60 * 1000,  // 5 attempts per minute10    },11    handler: async ({ body }) => { /* ... */ },12  });13}

#Health Check

AlephaServerHealth adds a GET /health endpoint that returns 200 OK. Import from alepha/server/health.

typescript 
1import { Alepha } from "alepha";2import { AlephaServerHealth } from "alepha/server/health";3 4Alepha.create()5  .with(AlephaServerHealth)6  .with(App)7  .start();

Use this for load balancer health probes and container orchestration readiness checks.

#Metrics

AlephaServerMetrics exposes a Prometheus-compatible metrics endpoint. Import from alepha/server/metrics.

typescript 
1import { Alepha } from "alepha";2import { AlephaServerMetrics } from "alepha/server/metrics";3 4Alepha.create()5  .with(AlephaServerMetrics)6  .with(App)7  .start();

Serves metrics in Prometheus text format at /metrics.

#Combining Middlewares

Register multiple modules together:

typescript 
 1import { Alepha } from "alepha"; 2import { $cors } from "alepha/server/cors"; 3import { $rateLimit } from "alepha/server/rate-limit"; 4import { AlephaServerHealth } from "alepha/server/health"; 5  6class App { 7  cors = $cors({ origin: "https://app.example.com" }); 8  limit = $rateLimit({ max: 100, windowMs: 15 * 60 * 1000 }); 9}10 11Alepha.create()12  .with(AlephaServerHealth)13  .with(App)14  .start();

Module order in .with() calls does not affect execution order. Alepha uses hook priorities internally to ensure correct ordering (e.g., CORS headers are set before the handler runs).