HeliumTS is under active development and may have bugs or breaking changes. Report issues on GitHub.
Configuration
Helium's configuration file lets you customize server behavior, HTTP RPC security, payload limits, and proxy handling from one place. Create helium.config.ts, helium.config.js, or helium.config.mjs in your project root.
heliumts/client.Basic Configuration
1import type { HeliumConfig } from "heliumts/server";23const config: HeliumConfig = {4 // Your configuration here5};67export default config;
HTTP Security Headers
Control Helium's default headers, override specific values, or remove headers when needed.
1import type { HeliumConfig } from "heliumts/server";23const config: HeliumConfig = {4 security: {5 // Apply Helium defaults (X-Frame-Options, Referrer-Policy, etc.)6 defaultHeaders: true,78 // Final overrides applied last9 headerOverrides: {10 "X-Frame-Options": "SAMEORIGIN",11 "Permissions-Policy": null,12 "X-Custom-Security": "enabled",13 },1415 contentSecurityPolicy: "default-src 'self'; frame-ancestors 'self'",16 hsts: true,17 corsOrigins: ["https://app.example.com"],18 },19};2021export default config;
security.defaultHeaders: defaults totrue. Setfalsefor full manual control.security.headerOverrides: use strings to set/override headers andnullto remove a header.security.contentSecurityPolicy,security.hsts, andsecurity.corsOriginsremain supported.
RPC Configuration
All RPC uses HTTP. Calls queued together are split into concurrent batches of at most rpc.maxBatchSize calls (default 20). Per-IP request windows apply to ordinary and streaming RPC requests. HTTP response compression is negotiated automatically; there is no transport or socket-compression configuration.
Security and Rate Limiting
1const config: HeliumConfig = {2 rpc: {3 security: {4 maxRequestsPerWindow: 100,5 rateLimitWindowMs: 60000,6 tokenValidityMs: 30000,7 },8 },9};
maxRequestsPerWindowdefaults to100. Set0to disable.rateLimitWindowMsdefaults to60000.tokenValidityMsdefaults to30000.
Payload Limits
1const config: HeliumConfig = {2 rpc: {3 maxBodySize: 10_485_760,4 maxBatchSize: 50,5 },6};
maxBodySizedefault:1048576(1 MB).maxBatchSizedefault:20.
RPC request values may nest up to 128 containers (arrays and objects). This decoding limit applies in addition to the body-size and batch limits.
Proxy Configuration
Set trustProxyDepth to match your proxy chain so IP-based limits work correctly.
1const config: HeliumConfig = {2 trustProxyDepth: 1,3};
0(default): trust no proxy headers.1: recommended for most managed platforms.2+: for multi-proxy setups.
Security note: setting this value too high can allow spoofed client IPs.
Complete Example
1import type { HeliumConfig } from "heliumts/server";23const config: HeliumConfig = {4 trustProxyDepth: 1,5 rpc: {6 security: {7 maxRequestsPerWindow: 100,8 rateLimitWindowMs: 60000,9 tokenValidityMs: 30000,10 },11 maxBodySize: 10_485_760,12 maxBatchSize: 50,13 },14};1516export default config;
Environment-Specific Configuration
1import type { HeliumConfig } from "heliumts/server";23const isDevelopment = process.env.NODE_ENV === "development";4const isProduction = process.env.NODE_ENV === "production";56const config: HeliumConfig = {7 trustProxyDepth: isProduction ? 1 : 0,8 rpc: {9 security: {10 maxRequestsPerWindow: isDevelopment ? 1000 : 100,11 rateLimitWindowMs: 60000,12 tokenValidityMs: 30000,13 },14 },15};1617export default config;
Production Deployment Notes
helium build selects helium.config.js, helium.config.mjs, then helium.config.ts and bundles the selected file to dist/helium.config.js. Local imports are bundled with it; package dependencies remain external.
Both helium start and node dist/server.js check the build directory first, then the project root. Set HELIUM_CONFIG_DIRto override the config directory. A config build or evaluation error fails the build or startup instead of silently replacing your settings with defaults.
Configuration Loading Order
- Checks the
HELIUM_CONFIG_DIRenvironment variable. - Resolves config files in this order:
helium.config.js,helium.config.mjs, thenhelium.config.ts. TypeScript configs and their local imports are bundled before loading, including on Node.js 20.
Export a configuration object as the default export. Default settings apply only when no config file exists. Config caches are scoped to the project and config directory.