This is a development guide. If you want to know the guidelines we follow then read CONTRIBUTING.md.

Setup development environment

git clone https://github.com/recharts/recharts.git
cd recharts
npm install # the right Node version can be found in .nvmrc file

Linting and types

You may also want to enable ESLint and Prettier configuration in your favourite IDE.

npm run lint
npm run check-types

Import restrictions

The project enforces that all imports from recharts must use the public API entry point. Imports from internal paths like recharts/types/* or recharts/src/* are not allowed and will fail the linter.

Good:

import { TooltipIndex, DataKey, BarRectangleItem } from 'recharts';

Bad:

import { TooltipIndex } from 'recharts/types/state/tooltipSlice'; // ❌ Will fail lint
import { DataKey } from 'recharts/src/util/types'; // ❌ Will fail lint

This ensures that consumers of the library only depend on stable, public APIs.

Automated testing

Running unit tests

Most unit tests are in the test directory, some others are in www/test.

Run all tests:

npm run test

Run a specific test file:

npm run test -- path/to/TestFile.spec.tsx

Running mutation tests

Mutation tests may take several hours to complete. You may want to first open ./stryker.config.mjs and set the mutate property to a specific file or directory that you want to test. That may take 5-10 minutes to run.

Mutation tests do not run in CI.

npm run test-mutation

Storybook

To run the Storybook UI:

npm run storybook

and then browse to http://localhost:6006.

While the storybook is running:

npm run test-storybook

Run visual regression tests (using playwright)

Prerequisites

Playwright tests are running inside Docker. You will need to have Docker installed and running. See https://docs.docker.com/get-started/get-docker/. You do not need Docker account or login.

You only need to do this once.

Build the Docker image

This takes two or three minutes to complete. You will need to re-build every time you make a change to dependencies in package.json.

npm run test-vr:prepare

Run the tests

Now, the usual loop. Write a new test, run it, fix it, repeat.

npm run test-vr

Alternatively, the UI playwright mode is available as well:

npm run test-vr:ui

If you want to record new snapshots or update the old ones, you can run:

npm run test-vr:update

You will see new files created in the test-vr/__snapshots__ directory, please commit them to the repository!

See VR test results

Open http://localhost:9323 in your browser to see the results of the tests. The CLI will tell you to run a "show-report" which is not necessary because there is already a Docker container running in the background and serving the report. Just open the URL in your browser.

Manual testing

recharts.github.io local run

To manually test Recharts in a real application environment, you can use the www directory which contains the source code for the Recharts documentation website https://recharts.github.io.

You can add a new example and commit it too!

To run the website locally in dev mode with hot-reloading:

npm run start -w www

When running locally, the website pulls the Recharts library from the local filesystem.

When you make changes to the Recharts source code, you need to re-build it for the changes to be reflected in the website:

npm run build

In production build, the website pulls recharts from npm registry.

Storybook

You can also use Storybook for manual testing of individual components.

npm run storybook

When adding new stories, mind that all stories here are also used for automated visual regression tests, using Chromatic cloud infrastructure.

Chromatic are very generous and free for open source projects, however we already have so many stories that we hit the limit for open source plan in some months.

For this reason, try to keep storybook for high fidelity examples, the ones you want to see published on the website and in storybook UI. For low fidelity tests, use unit tests or VR tests instead.

Playwright UI mode

You can also use Playwright in UI mode for manual testing. This opens a browser window where you can see the tests running, and you can see before & after.

npm run test-vr:ui

Releases

Releases are automated via GH Actions - when a new release is created in GH, CI will trigger that:

1. Runs a build
2. Runs tests
3. Runs npm publish

Version increments and tagging are not automated at this time.

Release testing

Until we can automate more, it should be preferred to test as close to the results of npm publish as we possibly can. This ensures we don't publish unintended breaking changes. One way to do that is using yalc - npm i -g yalc.

1. Make your changes in recharts
2. yalc publish in recharts
3. yalc add recharts in your test package (ex: in a vite or webpack reach app with recharts installed, imported, and your recent changes used)
4. npm install
5. Test a local run, a build, etc.

Folder structure

Source code:

• src - source code for Recharts library
• test - unit tests
• test-vr - visual regression tests (using Playwright)
• www - source code for Recharts documentation website recharts.github.io
• storybook - Storybook stories for Recharts components, and Storybook config+scaffolding
• scripts - helper scripts for development and releases
• .husky and .github - git hooks and GitHub Actions workflows for CI

Autogenerated code:

Running npm run build generates the following folders:

• lib - compiled output of Recharts library in CJS format - published to npm
• es6 - compiled output of Recharts library in ESM format - published to npm
• umd - compiled output of Recharts library in UMD format - published to npm
• types - generated TypeScript declaration files - published to npm
• build - output of tsc build - we don't use this for anything at all I think

Running npm run test-coverage generates:

• coverage - code coverage report

Running npm run test-mutation generates:

• reports - mutation testing report

Running npm run omnidoc generates:

• all www/src/docs/api/*API.tsx files - these are later used to generate API reference pages on the website on URL /docs/api/*
• all storybook/stories/API/arg-types/*Args.ts files - these are later used by Storybook to show props tables for components, and to generate controls for props in Storybook UI
• www/src/docs/api/index.ts - exports all generated API docs

These generated files are excluded from the repository via .gitignore to reduce noise. They are generated automatically during build. If you need to add a manual file in these directories (e.g. a manual MDX file), you must force add it to git: git add -f path/to/file.

If you want to modify any of the autogenerated code, you need to modify the JSDoc comments and/or TypeScript definitions in the appropriate source files in src folder, and then run npm run omnidoc to update the generated files. The npm run omnidoc command is also run automatically as part of npm run build.