chords-db is a plain JavaScript file per chord, and that is the whole design

One file per chord, and nothing else in the file

chords-db is a JavaScript database of chords for string instruments, and the design decision is that the source of truth is human-readable JavaScript rather than a binary or a generated artefact. The README walks through the schema by example, taking the `Dsus2` chord of guitar and showing the `D/sus2.js` file.

export default {
  key: 'D',
  suffix: 'sus2',
  positions: [{
    frets: '0320xx',
    fingers: '031000'
  },
  {
    frets: '55775x',
    fingers: '114310',
    barres: 5,
    capo: true
  }]
}

The object has a `key` and a `suffix`, and then a `positions` array where each entry is one playable variation of the chord. The `frets` string gives the fret number for each string, with `x` marking a string that is not played, and the `fingers` string gives a fingering for each string so a human can read the shape at a glance. Two optional fields handle the harder shapes. `barres` records the fret at which a string is barred, and `capo` is there for the case where you would rather express that barre as a capo position. The filename convention follows from the fields, with the key and suffix in the name.

Why one file per chord rather than one big file

The consequences of that layout are worth spelling out, because they are the actual argument for the project. Adding a chord is a pull request that touches one file and touches no other file, so two contributors adding two chords never conflict with each other. Reviewing a contribution means reading one small object rather than diffing a wall of data. And the schema is self-documenting: the README says to take a look at the chords database of an instrument to understand the schema used to register new chords, which is a statement that the data is meant to be read as documentation. The cost is file count. A database of many chords and many instruments is a large number of small modules, and a consumer that wants the whole set has to go through the build step rather than importing a single file. The library ships the compiled JSON, and the `lib` directory at the top level of the repository is where that lands. The project is open and free to use, and the README notes it is still missing a lot of chords and instruments, which is an invitation to fill the gaps.

Building the JSON library and running the tests

The project uses yarn as its package manager, and the README says the basic commands for the project lifecycle are bound to it. There are three commands you need. The build regenerates a new version of the library when new chords are added, and the test command does some testing of the newly added chords, which the README describes as very useful to detect basic mistakes. The package manifest shows exactly what they run. `yarn build` maps to `babel-node src/generate json`, so the generator is a script under `src/` that takes a `json` argument, and `yarn test` maps to `jest src`, running the test suite over the source tree with the jest configuration set to bail on the first failure. There is also a `stdout` script that runs the same generator without the `json` argument, and the `prepublish` hook runs the build, so a published package always contains freshly generated output. Formatting is handled by prettier with single quotes, wired into a lint-staged pre-commit hook through husky.

yarn build

yarn test

Note the version of the tooling in the manifest, since it is not the newest: jest 30, prettier 2, babel 7, and lint-staged 10. The package is published as `@tombatossals/chords-db` at version 0.6.0.

The data is shapes, and it is meant to be rendered by something else

The usage model is deliberately narrow. The README says all the information is packed in a JSON library that you can use to render visually with a utility able to parse this information. So chords-db is not a player and not a teaching app; it is the structured data layer, and the rendering is somebody else's problem. That is why the schema contains no audio, no tablature, no timing and no theory, only the physical description of where the fingers go. The project points at a live SVG rendering tool hosted on GitHub Pages, and the image it links to comes from the `react-chords` repository, which is the companion React project that consumes this data. If you are evaluating chords-db, the useful question is whether the rendering and the theory are your problem or your competitor's, because the data model assumes you only need the shapes. The topics confirm the scope, with guitar, guitar-chords, ukulele and ukulele-chords, and the description says string instruments in general, so the schema is intended to carry instruments beyond the two that are named.

The limits: coverage and the age of the data

There are two honest limits, and one of them is stated plainly in the README. The first is coverage. The project says contributions are welcomed and that there are still a lot of chords and instruments missing, and it asks people to use the pull request feature to add the chords they want. That is an invitation, but it is also an admission that a product built on this data will not have every shape for every key and every instrument on day one. If your application needs a specific chord, the practical cost is a pull request and a wait, or a fallback in your own code. The second limit is the passage of time. The last push to the repository was on 2026-05-09, and the package version is 0.6.0, which tells you the data format has not changed much. There are no GitHub releases, so there is no tagged history to diff when you upgrade, though a CHANGELOG.md is present at the top level. The licence is MIT, so you can embed the data in a commercial product without obligation beyond keeping the notice, and the author is named in the manifest along with the keywords music, node and javascript.

Editorial conclusion

Adopt chords-db if you are building a chord display, practice tool or guitar and ukulele app and want a permissive, hand-editable source of chord shapes rather than a paid API. Skip it if you need playback, tablature or audio, since the data is shapes only, and skip it if you expect complete coverage, because the project states that many chords and instruments are still missing. Before you rely on it, run `yarn test` and check the coverage of the specific chords your product needs, then add what is absent through a pull request in the schema the README documents.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. tombatossals/chords-db on GitHub