Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/theonetrade/backtest-monorepo-parallel/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you from a fresh clone to a running parallel backtest across all nine default symbols. The entire sequence takes under five minutes on a machine that already has Docker installed. All commands assume the repository root as the working directory.
1
Verify Prerequisites
2
Before you begin, confirm that the following tools are available on your machine:
3
  • Node.js 18+ — required for parseArgs (built-in util module) and ESM support used by @backtest-kit/cli
  • Docker or Docker Compose — used to run MongoDB and Redis locally
  • TypeScript 5.0+ — listed as a peer dependency in package.json
    • 4
    node --version   # must be v18.0.0 or higher
docker --version
tsc --version    # must be 5.0.0 or higher
    5
    Clone the Repository
    6
    git clone https://github.com/theonetrade/backtest-monorepo-parallel.git
cd backtest-monorepo-parallel
    7
    Install Dependencies
    8
    Install all root-level and workspace-level dependencies with a single command. npm workspaces will hoist shared packages and link @pro/core and @pro/main correctly.
    9
    npm install
    10
    Start MongoDB
    11
    The repository ships a ready-made Docker Compose file for MongoDB. This starts a standalone Mongo instance on the default port 27017.
    12
    docker-compose -f docker/mongodb/docker-compose.yaml up -d
    13
    Start Redis
    14
    Similarly, a Redis compose file is provided. Redis runs on port 6379 and is used by BaseMap for O(1) per-key caching.
    15
    docker-compose -f docker/redis/docker-compose.yaml up -d
    16
    Configure Environment Variables
    17
    Copy the example environment file and edit it to match your local setup:
    18
    cp .env.example .env
    19
    The relevant variables and their defaults are:
    20
    VariableDefaultPurposeCC_MONGO_CONNECTION_STRINGmongodb://localhost:27017/backtest-pro?wtimeoutMS=15000Mongo connection string for all DbService writesCC_REDIS_HOST127.0.0.1Redis hostname for BaseMap lookupsCC_REDIS_PORT6379Redis portCC_REDIS_USERdefaultRedis ACL usernameCC_REDIS_PASSWORDmysecurepasswordRedis ACL passwordCC_SYMBOL_LISTBTCUSDT,POLUSDT,ZECUSDT,HYPEUSDT,XAUTUSDT,DOGEUSDT,SOLUSDT,PENGUUSDT,HBARUSDTComma-separated list of symbols for the parallel Mode A runner
    21
    If you used the included Docker Compose files without modification, the defaults will work as-is.
    22
    Build All Packages
    23
    The monorepo uses Rollup to build each package in ./packages/* into a CommonJS bundle and a rolled-up type declaration file. Run the build for your platform:
    24
    Linux / macOS
    npm run build
    Windows
    npm run build:win
    25
    Under the hood, npm run build calls dotenv -e .env -- ./scripts/linux/build.sh, which iterates every directory under packages/ and runs npm run build inside each:
    26
    #!/bin/bash
cd packages
for D in `find . -maxdepth 1 -not -path "." -not -path "./.*" -type d`
do
    cd $D
    npm install
    npm run build
    cd ..
done
cd ..
    27
    Each successful build emits two artifacts per package:
    28
  • packages/<pkg>/build/index.cjs — the CommonJS bundle loaded at runtime via config/alias.config.ts
  • packages/<pkg>/types.d.ts — the rolled-up .d.ts bundle resolved at compile time via tsconfig.json paths
    • 29
    Run the Parallel Backtest (Mode A)
    30
    With infrastructure running and packages built, launch the parallel 9-symbol backtest using Mode A with the --cache flag to pre-warm all candles before the runners start:
    31
    npm run start -- --backtest --entry --ui --cache \
  ./content/apr_2026.strategy/apr_2026.strategy.ts
    32
    Flag reference:
    33
    FlagEffect--backtestActivates backtest mode in @pro/main; without it every mode handler early-returns--entryActivates the parallel entry gate in packages/main/src/main/backtest.ts that iterates CC_SYMBOL_LIST and calls Backtest.background(symbol, …) for each--uiStarts the @backtest-kit/ui web dashboard on port 60050--cacheCalls cacheCandles(…) for every symbol before the runners start, so the inner loop never blocks on ccxt HTTP
    34
    The --ui flag starts the optional @backtest-kit/ui web dashboard at http://localhost:60050. You can open it in any browser while the backtest is running to inspect positions, equity curves, and per-symbol activity in real time.
    35
    Omitting --cache on the first run means the inner loop will call ccxt over HTTP to fetch 1-minute candles for each symbol as they are needed. This is significantly slower than the cached path — expect the throughput to drop from ~103 events/sec to a rate limited by your internet connection and exchange API rate limits.
    36
    Observe the Output
    37
    Once all nine Backtest.background(...) calls are dispatched, the strategy file begins printing progress to the console. You should see output resembling:
    38
    active BTCUSDT backtest=1775001720000 now=1779292949309
active SOLUSDT backtest=1775001720000 now=1779292949415
active DOGEUSDT backtest=1775001720000 now=1779292949521
active HBARUSDT backtest=1775001720000 now=1779292949633
...
    39
    Each line is one listenActivePing event from a symbol runner. Across the full captured run, 297 events fire across 9 symbols in ~2.9 seconds — an aggregate throughput of approximately 103 events/sec and ≈ 6 326× real-time replay speed.

    ​
    Running Mode B (Single-Symbol)

    If you want to run a single-strategy backtest without the parallel entry gate — letting @backtest-kit/cli manage the symbol dispatch — omit --entry: 
    npm run start -- --backtest --ui \
  ./content/apr_2026.strategy/apr_2026.strategy.ts
    Without --entry, packages/main/src/main/backtest.ts early-returns and the bundled CLI takes over: it loads the strategy file, calls schemas registered inside it, and runs a single backtest on whatever symbol the strategy itself declares.

    ​
    Next Steps

    Architecture

    Understand how the two packages are wired together, how globalThis.core is set up, and how config files bootstrap the runtime without bundler hooks.

    Introduction

    Read the full feature overview, performance table, and explanation of why the system is as fast as it is.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us