Lightweight Charts React Components
Development guidelines for building and maintaining a React wrapper library for TradingView's Lightweight Charts.
Library Overview
This is a modern, ESM-only React library that wraps TradingView's Lightweight Charts with idiomatic React components. The repository contains library code under `lib/` directory and example usage.
Architecture Guidelines
Module System
Use ESM-only syntax throughout the codebaseSupport tree-shaking by keeping exports modular and side-effect freeUse named exports for all components and hooksAvoid default exports unless absolutely necessaryDependencies
lightweight-charts is a peer dependency (version 5+ required)React 16.8.0+ is requiredDo not bundle React or lightweight-chartsFile Structure
Library files are placed under `lib/` directory, not in the rootUse `.tsx` extension for all component filesKeep library organized and modular for optimal tree-shakingComponent Development
React Patterns
All components must be functional components using React Hooks onlyNo class components allowedUse the `use` prefix for all internal hooks (e.g., `useChart`, `useSeries`)Do not include React state or props unrelated to chart renderingKeep components focused on chart rendering logic onlyTypeScript Guidelines
Follow strict TypeScript typing throughoutAvoid `any` type unless absolutely necessaryName props interfaces as `ComponentNameProps`Ensure comprehensive type coverageWrite self-documenting code with clear type definitionsNaming Conventions
Use `PascalCase` for component namesUse `camelCase` for hook namesUse `PascalCase` for TypeScript interfaces and typesKeep names descriptive and consistent with React conventionsStyling & DOM
CSS Guidelines
Do not use external CSS filesThe library does not require any stylingNever use `className` or `style` props unless the chart component explicitly needs a wrapper divKeep the library presentation-agnosticCode Quality
Documentation
Write clear JSDoc comments for all public components and utilitiesDocument complex logic and non-obvious implementation detailsInclude usage examples in JSDoc where helpfulCode Style
Use `eslint` for lintingUse `prettier` for code formattingFollow the established code style consistentlyImplement comprehensive error handlingFollow security best practicesError Handling
Implement comprehensive error handling for chart operationsProvide clear error messages for invalid configurationsHandle edge cases gracefullyValidate props where appropriateTesting
Test Framework
Use Vitest as the testing frameworkMock DOM and chart dependencies where neededTest component behavior, not implementation detailsEnsure test coverage for public APIsTest Patterns
Write unit tests for individual components and hooksTest chart lifecycle methodsVerify proper cleanup on unmountTest error handling pathsBest Practices
Performance
Minimize unnecessary re-rendersUse React.memo where appropriateOptimize hook dependenciesAvoid creating new objects or functions in renderMaintainability
Write self-documenting codeKeep components small and focusedFollow single responsibility principleUse descriptive variable and function namesCompatibility
Ensure compatibility with lightweight-charts 5+Maintain backward compatibility within major versionsDocument breaking changes clearlyFollow semantic versioningExamples & Usage
Component Structure
```typescript
interface ChartComponentProps {
// Props interface
}
/**
* JSDoc comment describing the component
*/
export function ChartComponent(props: ChartComponentProps) {
// Implementation using hooks
}
```
Hook Structure
```typescript
/**
* JSDoc comment describing the hook
*/
export function useChartFeature() {
// Hook implementation
}
```
Development Workflow
1. Write TypeScript code with strict typing
2. Add JSDoc comments for public APIs
3. Write Vitest tests for new features
4. Run linting and formatting checks
5. Ensure tree-shaking compatibility
6. Test with lightweight-charts 5+
7. Update documentation as needed