Trading Chart Component

A powerful, provider-agnostic trading chart built on TradingView's Lightweight Charts library.

Features

Chart Visualization

• Real-time candlestick charts with volume
• Technical indicators (SMA, EMA, RSI, MACD, Bollinger Bands, VWAP, …)
• Interactive price lines for entry/exit levels
• Trade markers (entry/exit, win/loss colored) with a details popup
• Bar selection and inspection (clickable or externally controlled)
• Infinite scroll for historical data
• Context menu for quick actions
• Theming for the chart canvas and modals (see docs/theming.md)

Data Management

• Provider-agnostic architecture (works with any data source)
• Built-in Alpaca Markets integration
• Real-time WebSocket support
• Historical data fetching with pagination
• Data validation and normalization utilities
• Error handling and retry logic
• Easy to create custom adapters for other providers

Install (as a package)

npm install @adrienhobbs/candlekit lightweight-charts react react-dom

react, react-dom, and lightweight-charts are peer dependencies — install them alongside the package.

import { ChartComponent } from '@adrienhobbs/candlekit';
import '@adrienhobbs/candlekit/styles.css';

<ChartComponent bars={bars} />

Indicator overlays persist via localStorage by default (createPersistenceAdapter('localStorage')), or pass 'noop' to disable.

Quick Start

The sections below describe the dev harness (npm run dev) bundled in this repo, not the published package.

Option 1: With Mock Data (No Setup Required)

npm install
npm run dev

The app will run with realistic mock data - perfect for testing and development.

Option 2: With Real Alpaca Market Data

1. Install dependencies:

npm install

2. Get free Alpaca API credentials (see below)

3. Copy .env.example to .env and add your credentials:

cp .env.example .env

Edit .env:

VITE_ALPACA_API_KEY=your-api-key
VITE_ALPACA_SECRET_KEY=your-secret-key

4. Run the development server:

npm run dev

The app will automatically detect your API keys and switch to real market data!

Getting Alpaca API Credentials

1. Sign up for a free account at Alpaca Markets
2. Navigate to the Paper Trading Dashboard
3. Go to "Your API Keys" section
4. Generate new API keys
5. Copy the API Key ID and Secret Key to your .env file

Documentation

See the docs folder for comprehensive documentation:

• Data Management Guide - Complete guide to fetching and managing market data
• ChartComponent Usage - Complete guide to using the chart
• Theming - Theme the chart canvas + modals/popups
• Creating Indicators - Build custom indicators
• Architecture - System design and architecture
• API Reference - Complete API documentation
• Examples - Code examples and recipes

Project Structure

src/
├── components/          # React components
│   ├── ChartComponent.tsx
│   ├── IndicatorBrowser.tsx
│   └── SettingsDialog.tsx
├── hooks/              # Custom React hooks
│   ├── useBarsData.ts      # Data management hook
│   ├── useChartAPI.ts      # Chart API hook
│   └── useRealtimeUpdates.ts (deprecated)
├── adapters/           # Data provider adapters
│   ├── types.ts
│   └── alpaca.ts
├── indicators/         # Technical indicators
│   ├── core/
│   ├── primitives/
│   ├── registry/
│   └── utils/
├── types/             # TypeScript type definitions
└── utils/             # Utility functions

License

MIT