halide（halide 命令行）

Overview

Halide is a declarative BFF (Backend for Frontend) runtime built on Hono. It standardizes how SPAs communicate with backend services by providing a shared, predictable structure for auth, routing, proxying, and security.

When to use: You have a SPA (Angular, React, Vue, Svelte) and need a BFF layer between it and your backend services.

When not to use: You need direct HTTP layer control, multi-service routing, circuit breakers, load balancing, or TLS termination — use an API gateway or service mesh instead.

Installation

npm install halide

Or use the CLI to scaffold a server:

npx halide init

Requires Node.js >= 24.0.0. This is an ESM project ("type": "module").

Quick Start

import { createServer, apiRoute, proxyRoute } from 'halide';

const server = createServer({
  spa: {
    name: 'my-app',
    root: 'dist',
  },
  apiRoutes: [
    apiRoute({
      access: 'public',
      method: 'get',
      path: '/api/health',
      handler: async () => ({ status: 'ok' }),
    }),
  ],
  proxyRoutes: [
    proxyRoute({
      access: 'private',
      methods: ['get'],
      path: '/api/users',
      target: 'http://user-svc:3000',
    }),
  ],
});

server.start((port) => {
  console.log(`Server running on port ${port}`);
});

Run with: npx tsx server.ts

Exports

All imports come from 'halide':

Server Lifecycle

const server = createServer(config);
server.start((port) => {
  console.log(`Listening on ${port}`);
});
await server.ready;
await server.stop(); // graceful shutdown

• createServer() is synchronous — no await needed
• SIGINT/SIGTERM are handled automatically

Error Handling

All unhandled errors are caught and return 500 Internal Server Error with {error: 'Internal Server Error'}. Errors are logged via the configured logger.

Gotchas

• Framework: Hono (not Express). All HTTP types come from hono
• Config shape: ServerConfig uses separate arrays: apiRoutes + proxyRoutes, NOT a single routes array
• Auth config is nested: security.auth.strategy — not a top-level auth key
• Handler signature: (ctx, claims, logger) — 3 parameters. ctx is a plain object, NOT a Hono Context
• CSP directives: Must use camelCase (defaultSrc), NOT kebab-case (default-src) — validator throws on kebab-case
• Private routes require auth: If any route has access: 'private', security.auth must be configured
• CORS wildcard: origin: '*' cannot be combined with credentials: true — validator throws
• apiPrefix: Defaults to '/api' — paths starting with this prefix get 404 instead of SPA fallback. Set apiPrefix: '' to disable
• Default port: 3553 (from PORT env → spa.port → default)
• Proxy route methods required: methods array is required and must have at least one method
• Route paths must start with /: Validation throws otherwise
• Proxy host header: The original Host header is NOT forwarded — it's derived from the target URL. Original host is preserved as X-Forwarded-Host
• Proxy readonly headers: host, connection, content-length, transfer-encoding, set-cookie cannot be overridden by identity or transform
• Bearer secret caching: secretTtl defaults to 60 seconds. Set to 0 to disable caching
• OpenAPI CSP warning: When OpenAPI is enabled, Scalar UI routes use relaxed CSP; custom CSP does not apply to those routes. A warning is logged at startup

Reference Files

• Configuration — ServerConfig, SpaConfig, SecurityConfig, types
• Authentication — Bearer, JWKS, authorization functions, claims
• Routes — API routes, proxy routes, path rewriting, identity, transform
• Security — CORS, CSP (directives table), rate limiting
• Observability — Logger, lifecycle hooks, request ID
• OpenAPI — OpenAPI configuration, per-route metadata

Fallback: Reading Installed Package

If you need to verify types or behavior beyond what this skill covers, look in the consuming project's node_modules/halide/:

• node_modules/halide/dist/index.d.ts — all exported types and function signatures
• node_modules/halide/dist/index.js — ESM entry point
• node_modules/halide/package.json — version, dependencies, exports map