free-exercise-db: Using the Exercise JSON Dataset and Vue Site

Why free-exercise-db exists for fitness application developers

free-exercise-db addresses a specific data problem: finding exercise records that can be browsed, searched, and incorporated into a fitness application without first building a collection from scratch. The project says its author encountered the earlier `wrkout/exercises.json` dataset while building a fitness application, found that its structure did not match the desired shape, and reorganized it into a schema-driven collection with a public frontend.

The dataset is aimed at developers who need exercise names, classifications, instructions, and image references. Each record can identify the exercise's `force`, `level`, `mechanic`, `equipment`, `category`, primary muscles, secondary muscles, and image paths. Those attributes make the data useful for filters such as beginner strength exercises involving dumbbells or isolation movements that primarily target the biceps.

It also serves people who simply want to inspect the collection. The Vue site provides a searchable and browsable presentation, while the raw JSON can be fetched directly. That separation matters because an application may need machine-readable records without adopting the frontend.

The project is not positioned as a workout planner, exercise tracker, or clinical exercise system. The README does not document personal training logic, rep prescriptions, contraindications, or medical validation. Its narrower role is supplying structured content and images to another product.

The JSON record structure and image path flow

Each exercise is stored as a separate JSON document under `exercises/`, and those documents conform to `schema.json`. A record uses a string `id` based on its name, followed by descriptive fields. `primaryMuscles` and `secondaryMuscles` are arrays, `instructions` is an array of textual steps, and `images` contains relative paths to image files.

The README's `Alternate_Incline_Dumbbell_Curl` example shows the expected structure. It associates the exercise with `pull` force, `beginner` level, `isolation` mechanic, `dumbbell` equipment, `strength` category, `biceps` as the primary muscle, and `forearms` as a secondary muscle. This normalization allows an application to apply consistent filters rather than infer categories from exercise names.

The image paths are not complete URLs inside the JSON. A path such as `Air_Bike/0.jpg` must be resolved against a chosen host. The README documents GitHub's raw hosting as one option. It also points to `imagekit.io` as an option for dynamic resizing and says the frontend uses such an image service.

There are two output formats for bulk use. `dist/exercises.json` combines the records into one JSON array. `dist/exercises.nd.json` emits Newline Delimited JSON for PostgreSQL import workflows. The Makefile uses `jq` for both transformations. Consumers that expect one document per exercise, an array, or NDJSON must therefore select the appropriate distribution rather than treating every available file as interchangeable.

Installing the data tools and running the Vue catalog

A data consumer can clone the repository and use the exercise JSON and images locally. The README does not provide a dedicated package installation command for consuming the dataset because it is primarily repository content rather than a published application API. Validation requires the Python-based `check-jsonschema` tool, which the Makefile installs through the repository's `install` target.

After cloning the repository and changing to its root, install that dependency with the documented task.

make install

The target runs `pip install check-jsonschema`. It installs the validator used by the next command but does not download the dataset, since the dataset is already in the checkout. The `site` directory is a separate Vue project, so a developer interested in running the frontend also needs the Node.js dependencies for that directory.

The README lists these setup, development, test, build, and lint commands for the site:

npm install
npm run dev
npm run build
npm run test:unit
npm run test:e2e:dev
npm run lint

`npm install` installs the site dependencies. `npm run dev` starts the development workflow with compilation and hot reload, while `npm run build` creates the production build. `npm run test:unit` uses Vitest. `npm run test:e2e:dev` runs Cypress against the Vite development server; the README states that this is faster than testing the production build.

Before deployment, the documented production sequence is:

npm run build
npm run test:e2e

The first command compiles and minifies the site, and the second runs the Cypress end-to-end tests against that production build. The README presents this sequence as appropriate for deployment environments and CI.

Validating records and generating distributable JSON

The repository makes schema validation part of maintenance rather than relying only on the frontend. The `lint` target passes every source document to `check-jsonschema` with `schema.json` as the schema. This catches records that no longer conform to the project's declared structure.

From the repository root, run:

make lint

This does not guarantee that every field contains a medically useful or commercially acceptable value. The README explicitly lists `force`, `mechanic`, and `equipment` as incomplete in some JSON files. Those properties have to allow `null`, so schema-valid records can still contain missing classification data. An application should decide whether it omits such records, displays unknown values, or uses its own fallback categories.

After adding or modifying an exercise, regenerate the combined array with:

make dist/exercises.json

The task runs `jq` over the source files and writes a single JSON array. The README states that this command requires `jq`. It also documents a Newline Delimited JSON target:

make dist/exercises.nd.json

This output is intended for PostgreSQL import through the `COPY` command. The distinction can prevent an avoidable integration error: importing an array into a system that expects one JSON object per line, or importing NDJSON into a parser that expects a complete array, will require a conversion stage.

The Makefile also contains `check_dupes` and `check_missing_images`. The first finds duplicate `id` values. The second lists exercise documents whose `images` array is empty. Neither target is presented in the README as part of the normal build, but both are available repository maintenance operations.

Public domain licensing and hosted asset dependencies

The repository identifies the dataset as open public-domain data and uses the Unlicense. That designation is important for developers evaluating reuse, but the repository's documentation does not provide legal advice or a separate asset-by-asset rights analysis. The README credits the original dataset at `wrkout/exercises.json`, so users should preserve that provenance when redistributing or transforming the collection.

The hosted-image example relies on GitHub's raw-content domain, while the frontend's resizing approach relies on an external image service. Local use can instead serve the `exercises/` assets directly. A production application should decide whether to copy images into its own object storage, proxy requests through the frontend, or depend on the documented remote URLs. Each choice changes failure handling and network costs.

Remote URLs also couple the application to repository hosting and service availability. The README does not define a service-level agreement, cache policy, or image transformation budget. It also does not document rollback or a published compatibility policy for record fields. There are no GitHub releases, so a consumer should treat the default branch as the source of truth rather than looking for versioned release artifacts.

The last push was on 2026-09-27, and the repository is not archived. That is current repository activity, but it does not itself establish long-term storage guarantees. Upgrades may require consumers to rerun validation and compare changed records if they pin a snapshot.

Limitations compared with wrkout/exercises.json and Datasette

The clearest alternative discussed by the project is `wrkout/exercises.json`, the source collection credited in the README. According to the project description, that dataset was useful, but its data was not structured in the way the author wanted. free-exercise-db restructures it and adds a Vue frontend. A developer who already depends on the original project's exact fields should therefore compare schemas rather than assuming this is a drop-in replacement.

Datasette provides a different inspection route. The README links a `lite.datasette.io` view for exploring the combined dataset with facets over fields such as `primaryMuscles`, `force`, `level`, and `equipment`. That approach is useful for querying and exploring the data without adopting the Vue site. free-exercise-db's frontend instead presents the collection as its own public catalog and is also the code base intended for localized customization.

free-exercise-db has clear content limitations. Some records have incomplete fields, and the TODO reports a small number of duplicate image files. The example in the README also has a JSON syntax issue: its only string in `instructions` ends with a comma before the array closes. The project directs contributors to `schema.json` and the contribution guidelines, but the README does not explain how such discrepancies are triaged. Integrators need to validate syntax, missing values, image paths, and duplicates instead of trusting the catalog count alone.

It is the wrong choice when an application requires guaranteed image uniqueness, complete equipment classifications, versioned releases, or domain-reviewed exercise instructions. Those requirements are not established by this repository.

Editorial conclusion

Adopt free-exercise-db when an application needs a broad exercise catalog and public-domain JSON with hosted images. Do not treat it as a medically reviewed instruction set or assume every record is complete. Before integration, inspect schema compatibility, missing values, duplicate imagery, image availability, and the operational cost of copying records into your own product.

Frequently asked questions

Official sources

1. Issues
2. License: Unlicense
3. Project website
4. README
5. yuhonas/free-exercise-db on GitHub