Onboarding: frappe/charts

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/frappe/charts shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across all four use cases

• Last commit 10mo ago
• 16 active contributors
• Distributed ownership (top contributor 47% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 10mo ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live frappe/charts repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/frappe/charts.

What it runs against: a local clone of frappe/charts — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in frappe/charts | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 338 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>frappe/charts</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of frappe/charts. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/frappe/charts.git
#   cd charts
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of frappe/charts and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "frappe/charts(\\.git)?\\b" \\
  && ok "origin remote is frappe/charts" \\
  || miss "origin remote is not frappe/charts (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/js/chart.js" \\
  && ok "src/js/chart.js" \\
  || miss "missing critical file: src/js/chart.js"
test -f "src/js/charts/BaseChart.js" \\
  && ok "src/js/charts/BaseChart.js" \\
  || miss "missing critical file: src/js/charts/BaseChart.js"
test -f "src/js/charts/AxisChart.js" \\
  && ok "src/js/charts/AxisChart.js" \\
  || miss "missing critical file: src/js/charts/AxisChart.js"
test -f "src/js/objects/ChartComponents.js" \\
  && ok "src/js/objects/ChartComponents.js" \\
  || miss "missing critical file: src/js/objects/ChartComponents.js"
test -f "src/js/utils/draw.js" \\
  && ok "src/js/utils/draw.js" \\
  || miss "missing critical file: src/js/utils/draw.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 338 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~308d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/frappe/charts"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Frappe Charts is a zero-dependency SVG charting library that renders GitHub-inspired, responsive charts (bar, line, area, pie, heatmap, mixed-axis) with a minimal API surface. It solves the problem of needing lightweight, dependency-free charts without the complexity of D3.js or c3.js, originally built to display sales history in ERPNext without pulling in heavy visualization stacks. Simple ES6 module structure: src/js/chart.js is the entry point, routing to specialized chart classes (AxisChart.js, PercentageChart.js, DonutChart.js, etc.) under src/js/charts/. All charts inherit from BaseChart.js. Styling lives in src/css/charts.scss. Built with Rollup (rollup.config.js) to produce UMD, ESM, and CommonJS bundles in dist/.

Who it's for

Full-stack developers and product teams building dashboards, admin panels, or business intelligence features who need simple, customizable charts without learning D3 or managing complex dependencies. Specifically, ERPNext users and anyone building lightweight web applications requiring quick data visualization.

Maturity & risk

Production-ready: version 1.6.3 is stable with CI/CD via GitHub Actions (npm-publish.yml). The codebase is well-structured with SCSS styling, ES6 modules, and Rollup bundling. However, there are no visible unit tests (test script just echoes an error), indicating gaps in test coverage despite the library's maturity.

Low risk for adoption: zero dependencies means no supply-chain vulnerabilities or version conflicts. However, the single-maintainer structure (Prateeksha Singh listed as author) creates bus-factor risk. Absence of automated tests makes refactoring dangerous. No visible CHANGELOG or release notes in the file structure suggest minimal community contribution infrastructure.

Active areas of work

Last visible activity is the npm-publish.yml workflow and v1.6.3 release. No indication of active development branches or pending PRs in the file structure. The repo appears to be in maintenance mode—stable but not actively evolving with new features.

Get running

git clone https://github.com/frappe/charts.git
cd charts
npm install
npm run build

Then npm run watch for live development mode.

Daily commands:

npm run watch

Builds and re-compiles on file changes. npm run build for one-time production build. No dev server listed—charts are tested by importing dist/frappe-charts.esm.js or dist/frappe-charts.umd.js into HTML/JS projects.

Map of the codebase

• src/js/chart.js — Main entry point and Chart class constructor—every chart instance flows through here; defines the public API surface.
• src/js/charts/BaseChart.js — Abstract base class for all chart types; defines rendering lifecycle, data validation, and core SVG rendering pipeline.
• src/js/charts/AxisChart.js — Parent class for axis-based charts (Bar, Line); handles axis drawing, scaling, tooltips—critical for most visualizations.
• src/js/objects/ChartComponents.js — Factory and utilities for SVG components (axes, labels, legends); heavily reused across all chart types.
• src/js/utils/draw.js — Core SVG path and shape drawing utilities; used by all chart renderers to generate visual elements.
• rollup.config.js — Build configuration that produces ESM, CJS, and UMD bundles; required for publish and zero-dependency guarantee.
• src/css/charts.scss — Global styles for chart animations, tooltips, and responsive layout; compiled into the bundle.

How to make changes

Add a New Chart Type

1. Create a new chart class in src/js/charts/ that extends AxisChart (for axis-based) or BaseChart (for custom). Implement init(), draw(), and update() methods. (src/js/charts/NewChart.js)
2. In your class's draw() method, use draw.js utilities (drawLine, drawBar) and dom.js to create SVG elements and attach them to this.svg. (src/js/utils/draw.js)
3. If axis-based, call this.setupAxes() or axis-chart-utils functions for scaling. Use helpers.js to validate and normalize data. (src/js/utils/axis-chart-utils.js)
4. Export your class from src/js/index.js so it's available to consumers (e.g., export { NewChart }). (src/js/index.js)
5. Add any chart-specific CSS to src/css/charts.scss using SCSS variables for consistency. (src/css/charts.scss)

Add a New Utility Function or Helper

1. Determine the category: data processing (helpers.js), drawing (draw.js or draw-utils.js), DOM manipulation (dom.js), or animation (animate.js). (src/js/utils/helpers.js)
2. Add your function to the appropriate utility file. Keep functions pure and focused on a single responsibility. (src/js/utils/draw.js)
3. Export the function from its module (usually already module.exports or export). (src/js/utils/dom.js)
4. Import and use it in your chart class or other utilities. Run npm run build to verify no import errors. (rollup.config.js)

Customize Styling or Add a New Component

1. Edit src/css/charts.scss to add or modify styles. Use SCSS nesting and variables defined at the top of the file. (src/css/charts.scss)
2. If adding a reusable component (e.g., legend, annotation box), create a factory function in src/js/objects/ChartComponents.js. (src/js/objects/ChartComponents.js)
3. Use dom.js utilities (makeElement, style, on) to construct the DOM and apply CSS classes defined in charts.scss. (src/js/utils/dom.js)
4. Instantiate the component in your chart's init() or draw() method and append to this.wrapper or this.svg. (src/js/chart.js)

Why these technologies

• Pure JavaScript / Vanilla DOM — Zero dependencies; lightweight bundle; full control over rendering and animation; no framework overhead for simple charting.
• SVG for rendering — Scalable, vector-based graphics; hardware acceleration support; easy exports to PNG/SVG; works across all modern browsers.
• SCSS / CSS-in-JS — Encapsulated styles; animations with GPU acceleration (transforms, opacity); responsive behavior without JavaScript.
• Rollup bundler — Tree-shaking to eliminate dead code; produces multiple formats (ESM, CJS, UMD)

Traps & gotchas

No test runner configured (test script is a stub); chart behavior must be validated manually in browser. Rollup config uses rollup-plugin-terser which may silently mangle variable names in minified output—verify if debugging production issues. SCSS compilation via node-sass v8 (recent major version with native binding changes) may require Python/C++ build tools on some systems. The library modifies DOM directly (no virtual DOM); simultaneous updates to multiple chart instances may cause race conditions. No TypeScript definitions visible; consumers building TS projects will have type safety gaps.

Architecture

Concepts to learn

• SVG Path Rendering — Frappe Charts generates all chart visuals as scalable SVG paths (not canvas or DOM divs); understanding d3-style path generation (M/L/C commands) is essential to modify chart shapes or add custom chart types.
• Class-Based Inheritance Hierarchy — The chart architecture uses classical OOP (BaseChart → AxisChart → subclasses) to avoid code duplication; modifying or extending charts requires understanding ES6 class patterns and method overriding.
• CSS-in-JS via SCSS with Rollup — Styling is embedded in the UMD/ESM bundles via rollup-plugin-scss; changes to charts.scss automatically recompile and inject CSS into the output—deviating from this pattern breaks the build.
• Module Bundling with Rollup and Multiple Output Formats — The library exports UMD (for <script> tags), ESM (for import statements), and CommonJS simultaneously; understanding how Rollup orchestrates these formats is critical when debugging cross-environment issues or modifying build output.
• DOM Mutation and Direct Imperative Updates — Unlike React/Vue, Frappe Charts directly mutates the DOM and manages state imperatively; the Chart API allows addDataPoint() and removeDataPoint() that recalculate and re-render live, requiring careful lifecycle management.
• Tooltip Positioning and Event Delegation — SvgTip.js handles hover events and dynamically positions tooltips; understanding mouse event bubbling and viewport coordinate transforms (offsetX, offsetY) is essential for fixing tooltip placement bugs.
• Animation via RequestAnimationFrame — animate.js uses RAF and easing functions for smooth transitions; adding new animation types or debugging jank requires familiarity with frame-based animation and timing functions.

Related repos

• chartjs/Chart.js — Direct competitor: canvas-based charting library with more features but higher bundle size and external dependencies; good reference for API design patterns.
• apache/echarts — Industry-standard visualization library; much heavier but handles complex interactions and heatmaps that Frappe Charts keeps minimal.
• frappe/frappe — Parent project (ERPNext framework); Frappe Charts was built to solve charting needs in Frappe's dashboard/report modules.
• d3/d3 — Inspiration and contrast: D3 is low-level and powerful but requires significant learning; Frappe Charts is intentionally simpler for the 80% use case.
• plotly/plotly.js — Feature-rich alternative with better annotation/region support; Frappe Charts trades advanced features for zero dependencies.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for chart utilities (colors, helpers, date-utils)

The repo has 2 test files (colors.test.js, helpers.test.js) in src/js/utils/test/ but no tests for critical utilities like date-utils.js, axis-chart-utils.js, draw-utils.js, and intervals.js. These utilities are core to chart rendering and data processing. The package.json has 'test' as a stub ('echo "Error: no test specified"'). Adding proper Jest/Vitest setup with tests for these modules would prevent regressions and improve maintainability. This is especially critical since there are no integration tests either.

• [ ] Set up Jest or Vitest in package.json with proper config file
• [ ] Add unit tests for src/js/utils/date-utils.js (date parsing, formatting, interval calculations)
• [ ] Add unit tests for src/js/utils/axis-chart-utils.js (axis scaling, tick generation)
• [ ] Add unit tests for src/js/utils/intervals.js (interval logic used in time-series charts)
• [ ] Add unit tests for src/js/utils/draw-utils.js (SVG path and drawing calculations)
• [ ] Update npm test script to run Jest instead of placeholder
• [ ] Add test coverage reporting to CI workflow

Implement GitHub Actions workflow for automated build and asset validation

The repo has .github/workflows/npm-publish.yml for publishing but no workflow to validate builds on PRs. With complex Rollup config generating 3 output formats (ESM, UMD, CJS), builds can break silently. Current file structure shows dist/ is checked in, which creates merge conflicts. Need a workflow to: validate build succeeds, check bundle size doesn't regress, verify all three output formats are valid, and optionally run eslint from .eslintrc.json that exists but isn't enforced in CI.

• [ ] Create .github/workflows/build-validate.yml that runs on push/PR
• [ ] Add step to run 'npm run build' and verify dist/ files are generated
• [ ] Add step to run eslint against src/ using .eslintrc.json config
• [ ] Add bundlephobia size check step (repo already uses this badge, integrate API)
• [ ] Add step to verify all three output formats (ESM, UMD, CJS) in dist/ are valid JS
• [ ] Consider adding step to check for console.log/debugger statements left in code
• [ ] Document in README.md how to test locally before submitting PR

Add missing API documentation for chart component configuration options

The repo references docs/index.html and docs/docs.html but there's no structured documentation for the Chart configuration API itself. Looking at src/js/charts/ there are multiple chart types (AggregationChart, AxisChart, DonutChart, Heatmap, PercentageChart, PieChart) and src/js/objects/ has ChartComponents.js and SvgTip.js. The README is truncated and doesn't show configuration options. Contributors and users need clear documentation of: constructor parameters for each chart type, component configuration, tooltip customization (SvgTip), color palette options (src/js/utils/colors.js), and animation options (src/js/utils/animation.js).

• [ ] Create docs/API.md with structured API reference
• [ ] Document each chart type in src/js/charts/ with constructor parameters and examples
• [ ] Document ChartComponents.js configuration options with examples
• [ ] Document SvgTip.js tooltip customization with examples
• [ ] Document color customization using src/js/utils/colors.js utilities
• [ ] Document animation options from src/js/utils/animation.js with examples
• [ ] Add 'API Documentation' link to main README.md
• [ ] Add JSDoc comments to chart class constructors in src/js/charts/*.js for IDE autocomplete

Good first issues

• Add unit test suite for BaseChart.js and AxisChart.js using Jest or Vitest; the test script currently errors, blocking quality assurance on refactors.
• Generate TypeScript .d.ts definitions from JSDoc comments in src/js/chart.js and chart classes; no types published breaks IDE autocomplete for TS consumers.
• Document the ChartComponents.js composition system with a guide in docs/ showing how to extend chart types; currently undocumented but critical for custom chart contributions.

Top contributors

• @uhrjun — 47 commits
• @scmmishra — 26 commits
• [@Kaleb White](https://github.com/Kaleb White) — 9 commits
• @dependabot[bot] — 4 commits
• @netchampfaris — 2 commits

Recent commits

• 7b15424 — chore: simplify usage section (netchampfaris)
• 6d05a89 — Update README.md (netchampfaris)
• f333096 — feat: experimental! allow overrriding yAxisLabels (uhrjun)
• 3a16d6c — fix: force deprecate unmaintained animate (uhrjun)
• 8f69be0 — Merge pull request #410 from Sorizz/master (uhrjun)
• b9551c1 — Changing README file (Sorizz)
• 34436a9 — fix & chore: fix makeText(), cleaned unused imports (uhrjun)
• 4dabb9d — Merge commit '9f68f1ac5f7e8eb7a089d13b27d44fa0702d7931' (uhrjun)
• ae2ae01 — feat: pr 366 initial merge (uhrjun)
• 0781eb0 — fix: Aggregation chart data.labels (uhrjun)

Security observations

The Frappe Charts project has moderate security concerns, primarily stemming from severely outdated dependencies (some from 2020) with known vulnerabilities, and a complete lack of security testing in the CI/CD pipeline. While the codebase itself shows no obvious hardcoded secrets or major architectural flaws, the absence of security scanning, vulnerable dependency versions, and missing security documentation create significant risk. The library's nature as a DOM-manipulating charting tool also presents potential XSS vectors if user inputs aren't properly sanitized. Immediate action required: update all dependencies, implement npm audit in CI/CD, and establish a security reporting policy.

• High · Outdated and Vulnerable Dependencies — package.json - devDependencies. The project uses several outdated dependencies with known vulnerabilities. Notably: node-sass@^8.0.0 (deprecated and has security issues), @babel/core@^7.10.5 (from 2020), rollup@^2.21.0 (outdated), and rollup-plugin-terser@^6.1.0 (unmaintained). These versions contain known CVEs and lack security patches. Fix: Update all dependencies to their latest stable versions. Replace node-sass with dart-sass. Run 'npm audit' and 'npm audit fix' to identify and resolve known vulnerabilities. Implement automated dependency updates using Dependabot.
• High · No Security Testing Configuration — .github/workflows/npm-publish.yml. The project lacks any security scanning tools or vulnerability detection in its CI/CD pipeline. The npm-publish.yml workflow file provides no evidence of security checks, SAST analysis, or dependency auditing before publishing to npm. Fix: Integrate security tools into CI/CD: add 'npm audit' checks, consider using Snyk or similar vulnerability scanners, and implement GitHub's Dependabot security alerts. Fail builds if vulnerabilities are detected.
• Medium · Missing Content Security Policy Considerations — src/js/objects/SvgTip.js, src/js/utils/draw.js. As an SVG charting library that manipulates DOM and generates dynamic content, there are potential XSS attack vectors if user data is not properly sanitized. No evidence of XSS protection mechanisms or input validation in the codebase structure. Fix: Implement strict input validation and sanitization for all user-provided data. Escape SVG attributes and text content. Consider using a security-focused DOM manipulation library or DOMPurify for content sanitization. Add CSP headers in documentation.
• Medium · Lack of Security Documentation — Repository root, README.md. No SECURITY.md file or security policy defined. No clear guidance for reporting vulnerabilities responsibly. README is incomplete and doesn't mention security best practices. Fix: Create a SECURITY.md file with instructions for responsible vulnerability disclosure. Include security considerations in README. Define a security reporting process (e.g., security@frappe.io) for users to report vulnerabilities privately.
• Low · Missing Package Integrity Verification — package.json, rollup.config.js. No package-lock.json usage enforcement or integrity checking mechanisms configured. The presence of package-lock.json is good, but no lockfile validation in build processes. Fix: Enable npm audit on install. Use npm ci instead of npm install in CI/CD pipelines. Consider adding npm integrity checks and signed commits for releases.
• Low · No Secrets Management Best Practices Documented — Repository root. While no hardcoded secrets are evident, there's no .env.example or documentation on handling API keys or sensitive configuration if needed in future versions. Fix: Create documentation for secure configuration management. Add .env.example template if credentials may be needed. Document how to handle environment-specific secrets securely.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.