openkline

CLAUDE.md — OpenKline (core monorepo)

Guidance for AI agents (Claude Code and friends) working in this repository.

What this repo is

OpenKline is a fast, framework-agnostic OHLCV charting engine. This repo (rekurt/openkline) is the monorepo that ships the engine, @rekurt/openkline-core, plus the example apps. The React and Vue wrappers live in their own repositories:

• rekurt/openkline-react → @rekurt/openkline-react
• rekurt/openkline-vue → @rekurt/openkline-vue

Naming: “OpenKline” is the product/brand. “OHLCV” is the financial data type (Open-High-Low-Close-Volume) and stays in domain symbols such as the OHLCVChart class, useOHLCVChart, OHLCVChartRef, and the ohlcv() test helper. Do not rename those — they describe the data, not the brand.

Layout

packages/core/          @rekurt/openkline-core — the engine (zero runtime deps)
  src/
    OHLCVChart.ts        public facade / entry class
    rendering/           ChartEngine, layers, axes, legend, webgl/
    data/                CandleBuffer, CandleMerger, DataFeed, transports
    interaction/         Viewport, keyboard, pan/zoom, autoFollow
    indicators/          indicators + registry + createIndicator factory
    drawings/            buffer-anchored drawing tools + DrawingLayer
    transforms/          Heikin-Ashi, Renko
    series/ primitives/ markers/ profile/ compare/ alerts/ export/ i18n/
    state/               saveLayoutState / loadState serialization
    types.ts             shared types (Candle, IndicatorConfig, …)
examples/
  _shared/               @openkline-examples/shared — mock feed, symbols
  core/                  vanilla demo (port 5173)
  playground/            unified demo (port 5176)
docs/                    GUIDES, COMPARISON, PLUGINS, superpowers/ (design history)

Commands

npm install             # install workspace deps
npm run dev:playground  # unified demo  → http://localhost:5176
npm run dev:core        # vanilla demo  → http://localhost:5173

npm run lint            # ESLint, --max-warnings 0  (must stay at 0)
npm run typecheck       # strict tsc across all tsconfigs
npm test                # vitest (run mode) — 440+ tests
npm run build           # tsup bundle for @rekurt/openkline-core
npm run docs            # TypeDoc → docs/api/

Before pushing, the green bar is: lint + typecheck + test + build all pass.

Conventions

• Business logic lives in the core. The React/Vue wrappers are thin glue; never duplicate engine logic in a wrapper.
• Indicators are config objects, not classes, in user-facing APIs. Add new ones through the IndicatorConfig union + createIndicator factory + registry.ts, not by exposing constructors.
• Strict TypeScript, including noUncheckedIndexedAccess. No any escape hatches in new code.
• No silent catches. Route errors through ErrorReporter / the onError callback.
• Drawings & indicators anchor in buffer space so they stick to candles on pan/zoom.
• Match the surrounding file’s style; keep comment density and naming idiomatic.

Wrappers depend on a vendored core tarball

Until packages are published to npm, openkline-react and openkline-vue vendor a packed build of this core at vendor/rekurt-openkline-core.tgz. If you change the core’s public API or build output, those repos must refresh the tarball via their npm run update:core (which clones this repo, builds packages/core, and re-packs). Keep @rekurt/openkline-core’s exports and package.json name stable, or update both wrappers in lockstep.

Don’t

• Don’t rename the OHLCVChart / useOHLCVChart API symbols (domain terms).
• Don’t rewrite docs/superpowers/* or historical CHANGELOG entries — they are a design/decision record.
• Don’t add runtime dependencies to @rekurt/openkline-core.

This site is open source. Improve this page.