Note:

HeliumTS is under active development. Expect bugs and breaking changes. If you find any issues, please report them in our GitHub

A stable release is planned for early 2026.

Configuration

Helium's configuration file lets you customize server behavior, RPC transport, 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

Transport Mode

1const config: HeliumConfig = {
2    rpc: {
3        transport: "websocket",  // "websocket" | "http" | "auto"
4        autoHttpOnMobile: false,
5    },
6};

websocket (default): lowest latency after connection warm-up.
http: stateless request/response transport per call.
auto: chooses transport based on network and device conditions.
autoHttpOnMobile: if true, mobile devices prefer HTTP even when connected to Wi-Fi.

Compression

1const config: HeliumConfig = {
2    rpc: {
3        compression: {
4            enabled: true,
5            threshold: 1024,
6        },
7    },
8};

Compression uses WebSocket per-message deflate. Messages smaller than threshold are not compressed to avoid unnecessary overhead.

Security and Rate Limiting

1const config: HeliumConfig = {
2    rpc: {
3        security: {
4            maxConnectionsPerIP: 10,
5            maxMessagesPerWindow: 100,
6            rateLimitWindowMs: 60000,
7            tokenValidityMs: 30000,
8        },
9    },
10};

maxConnectionsPerIP defaults to 10. Set 0 to disable.
maxMessagesPerWindow defaults to 100. Set 0 to disable.
rateLimitWindowMs defaults to 60000.
tokenValidityMs defaults to 30000.

Payload Limits

1const config: HeliumConfig = {
2    rpc: {
3        maxWsPayload: 10_485_760,
4        maxBodySize: 10_485_760,
5        maxBatchSize: 50,
6    },
7};

maxWsPayload default: 1048576 (1 MB).
maxBodySize default: 1048576 (1 MB).
maxBatchSize default: 20.

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        transport: "websocket",
7        autoHttpOnMobile: false,
8        compression: {
9            enabled: true,
10            threshold: 1024,
11        },
12        security: {
13            maxConnectionsPerIP: 10,
14            maxMessagesPerWindow: 100,
15            rateLimitWindowMs: 60000,
16            tokenValidityMs: 30000,
17        },
18        maxWsPayload: 10_485_760,
19        maxBodySize: 10_485_760,
20        maxBatchSize: 50,
21    },
22};
23
24export 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        compression: {
10            enabled: isProduction,
11            threshold: 1024,
12        },
13        security: {
14            maxConnectionsPerIP: isDevelopment ? 100 : 10,
15            maxMessagesPerWindow: isDevelopment ? 1000 : 100,
16            rateLimitWindowMs: 60000,
17            tokenValidityMs: 30000,
18        },
19    },
20};
21
22export default config;

Production Deployment Notes

If helium.config.ts exists, helium build transpiles it to dist/helium.config.js.
If helium.config.js exists, it is copied to dist/helium.config.js.
If helium.config.mjs exists, it is copied to dist/helium.config.mjs.

At runtime, helium start checks the dist directory first, then the project root.

Configuration Loading Order

Checks the HELIUM_CONFIG_DIR environment variable.
Resolves config files in this order: helium.config.js, helium.config.mjs, then helium.config.ts (dev with Vite).