Documentation Index
Fetch the complete documentation index at: https://mintlify.com/hypertekorg/hyperstack/llms.txt
Use this file to discover all available pages before exploring further.
The hyperstack.toml file is the central configuration for your Hyperstack project. It defines your project metadata, SDK generation settings, build preferences, and stack definitions.
Creating Configuration
The easiest way to create hyperstack.toml is with the CLI:
This command:
- Creates
hyperstack.toml with a project name based on your directory
- Auto-discovers stacks from
.hyperstack/*.stack.json files
- Creates a
.hyperstack/ directory if it doesn’t exist
File Location
By default, the CLI looks for hyperstack.toml in the current directory. You can specify a different path:
hs --config ./config/hyperstack.toml up
Minimal Configuration
For most projects, you only need a project name:
[project]
name = "my-stack"
.hyperstack/*.stack.json files created during cargo build.
Full Configuration Reference
[project]
name = "my-project"
description = "A brief description of your project"
version = "1.0.0"
# SDK generation settings
[sdk]
output_dir = "./generated" # Default output for both languages
typescript_output_dir = "./frontend/src/generated" # Override for TypeScript only
rust_output_dir = "./crates/generated" # Override for Rust only
typescript_package = "@myorg/my-sdk" # Package name for TypeScript
rust_module_mode = false # Generate Rust SDKs as modules by default
# Build preferences
[build]
watch_by_default = true
# Stack definitions (auto-discovered by default, but can be explicit)
[[stacks]]
name = "my-game"
stack = "SettlementGame" # Stack name or path to .stack.json
description = "Settlement game tracking"
typescript_output_file = "./src/generated/game.ts" # Per-stack TypeScript output path
rust_output_crate = "./crates/game-stack" # Per-stack Rust output path
rust_module = true # Per-stack: generate as module instead of crate
Configuration Sections
| Option | Type | Required | Description |
|---|
name | string | Yes | Project name (used for SDK package naming) |
description | string | No | Project description |
version | string | No | Project version |
[sdk] — SDK Generation Settings
| Option | Type | Default | Description |
|---|
output_dir | string | "./generated" | Default output directory for all SDKs |
typescript_output_dir | string | output_dir | TypeScript SDK output directory |
rust_output_dir | string | output_dir | Rust SDK output directory |
typescript_package | string | "hyperstack-stacks/{stack_name}" | NPM package name for TypeScript SDKs |
rust_module_mode | boolean | false | Generate Rust SDKs as modules (mod.rs) instead of standalone crates |
rust_module_mode = true, generated Rust SDKs are created as modules that can be embedded directly in your existing crate. When false, each SDK is generated as a standalone crate with its own Cargo.toml.
:::
[build] — Build Preferences
| Option | Type | Default | Description |
|---|
watch_by_default | boolean | true | Enable file watching for automatic rebuilds during development |
[[stacks]] — Stack Definitions
Define stacks explicitly for custom naming or per-stack overrides. If not defined, stacks are auto-discovered from .hyperstack/*.stack.json files.
| Option | Type | Required | Description |
|---|
name | string | Yes | Stack name (used for SDK generation and CLI commands) |
stack | string | Yes | Stack name from your Rust code or path to .stack.json file |
description | string | No | Stack description |
typescript_output_file | string | No | Per-stack TypeScript output file path |
rust_output_crate | string | No | Per-stack Rust output crate/module directory |
rust_module | boolean | No | Per-stack override for module vs crate generation |
Common Use Cases
Multiple Stacks in One Project
Each stack is a separate #[hyperstack] module that can contain multiple entities. Use multiple [[stacks]] entries when you have separate programs or data sources:
[project]
name = "my-defi-protocol"
[[stacks]]
name = "lending"
stack = "LendingMarket"
description = "Lending pool positions and interest rates"
[[stacks]]
name = "dex"
stack = "DexPool"
description = "DEX liquidity pools and swaps"
Separate SDK Output Directories
[project]
name = "my-project"
[sdk]
typescript_output_dir = "./frontend/src/generated"
rust_output_dir = "./crates/generated"
Custom TypeScript Package Name
[project]
name = "my-project"
[sdk]
typescript_package = "@myorg/hyperstack-sdk"
Rust SDK as Module (for Monorepos)
[project]
name = "my-project"
[sdk]
rust_module_mode = true # All Rust SDKs generated as modules
[[stacks]]
name = "my-game"
stack = "SettlementGame"
rust_module = true
rust_output_crate = "./src/generated" # Will create mod.rs here
Per-Stack TypeScript Output File
[[stacks]]
name = "game"
stack = "GameState"
typescript_output_file = "./src/game.ts"
Environment Variables
Environment variables override configuration file values:
| Variable | Description | Overrides |
|---|
HYPERSTACK_API_URL | Override the API endpoint | Default API URL |
HYPERSTACK_API_KEY | API key for authentication | (no file override) |
Credentials File
Authentication credentials are stored separately in:
~/.hyperstack/credentials.toml
api_key = "your-api-key-here"
Validation
Validate your configuration:
This checks:
- Required fields are present
- File paths are valid
- Stack references resolve to valid
.stack.json files
- No conflicting settings
Example: ORE Stack Configuration
Here’s the real configuration from the ORE stack:
[project]
name = "ore"
[[stacks]]
name = "ore"
stack = "OreStream"
url = "wss://ore.stack.usehyperstack.com"
typescript_output_file = "../sdk/typescript/src/ore/index.ts"
rust_output_crate = "../sdk/rust/src/ore"
rust_module = true
Next Steps