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.

Built-in stale recovery: Helium includes client-side stale runtime recovery by default. Resume recovery and guarded reloads after chunk failures are always enabled when using heliumts/client.

Basic Configuration

1import type { HeliumConfig } from "heliumts/server";
2
3const config: HeliumConfig = {
4 // Your configuration here
5};
6
7export default config;

HTTP Security Headers

Control Helium's default headers, override specific values, or remove headers when needed.

1import type { HeliumConfig } from "heliumts/server";
2
3const config: HeliumConfig = {
4 security: {
5 // Apply Helium defaults (X-Frame-Options, Referrer-Policy, etc.)
6 defaultHeaders: true,
7
8 // Final overrides applied last
9 headerOverrides: {
10 "X-Frame-Options": "SAMEORIGIN",
11 "Permissions-Policy": null,
12 "X-Custom-Security": "enabled",
13 },
14
15 contentSecurityPolicy: "default-src 'self'; frame-ancestors 'self'",
16 hsts: true,
17 corsOrigins: ["https://app.example.com"],
18 },
19};
20
21export default config;
  • security.defaultHeaders: defaults to true. Set false for full manual control.
  • security.headerOverrides: use strings to set/override headers and null to remove a header.
  • security.contentSecurityPolicy, security.hsts, and security.corsOrigins remain 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};
  • maxRequestsPerWindow defaults to 100. Set 0 to disable.
  • rateLimitWindowMs defaults to 60000.
  • tokenValidityMs defaults to 30000.

Payload Limits

1const config: HeliumConfig = {
2 rpc: {
3 maxBodySize: 10_485_760,
4 maxBatchSize: 50,
5 },
6};
  • maxBodySize default: 1048576 (1 MB).
  • maxBatchSize default: 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";
2
3const 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};
15
16export default config;

Environment-Specific Configuration

1import type { HeliumConfig } from "heliumts/server";
2
3const isDevelopment = process.env.NODE_ENV === "development";
4const isProduction = process.env.NODE_ENV === "production";
5
6const 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};
16
17export 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

  1. Checks the HELIUM_CONFIG_DIR environment variable.
  2. Resolves config files in this order: helium.config.js, helium.config.mjs, then helium.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.