# Khan Perseus exercise renderer for interactive questions

> Perseus turns questions written in its exercise format into interactive experiences and grades learner responses. It suits teams studying Khan Academy's question system or building a compatible TypeScript question renderer, but its Node version conflict and closed contribution policy require attention.

**Khan/perseus** — Perseus is Khan Academy's exercise question editor and renderer.

- Repository: https://github.com/Khan/perseus
- Website: https://khan.github.io/perseus/
- Stars: 1,592 · Forks: 373
- Language: TypeScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/khan-perseus

## Perseus targets the Khan Academy exercise format

Perseus solves a specific assessment problem: taking a problem in the Perseus format and presenting it to a learner. The system also supports interaction and grading of the learner's work. That makes it different from a generic React component library. Its unit of content is an exercise, and its job extends beyond drawing form controls. The renderer must turn structured question data into an interface, accept input, and evaluate the result.

The intended audience includes engineers working with Khan Academy's exercise system, teams that need to understand its question format, and developers studying how interactive questions can be built and graded. The repository also contains packages named `@khanacademy/perseus-score` and `@khanacademy/perseus-linter`, which indicate that scoring and question validation are separate npm packages within the monorepo. The README calls Perseus an exercise system and describes the repository as containing the code needed to present, interact with, and grade questions.

That scope is attractive when compatibility with the Perseus format matters. It is less suitable when an application only needs a textarea, a quiz API, or a conventional form submission flow. Perseus is designed around a particular exercise model, not a general abstraction for every form of assessment.

## The renderer follows a content, interaction, grading pipeline

Based on the repository description, the main data flow is straightforward. A problem is authored in the Perseus format. Perseus presents that problem through its exercise components and widgets. The learner interacts with the rendered question, and the system grades the resulting work.

The repository layout shows that this is a TypeScript monorepo rather than one standalone source file. The `packages/` directory contains the package-level implementation, while `data/`, `docs/`, `types/`, and `config/` provide supporting repository assets and configuration. The released package names shown in the repository metadata separate the renderer, score handling, and linting concerns. The README does not document the complete internal component tree or the precise grading event API, so an adopter should not assume a particular callback or state shape without inspecting the package documentation and types.

Development also depends on a component workflow. Perseus components and widgets are developed in Storybook, where individual pieces can be viewed in a gallery. This is useful when changing a widget or checking its rendered states, but it also means the system is larger than a single rendering entry point. Consumers need to account for package inter-dependencies when integrating it.

## Monorepo setup and first Storybook launch

The README gives a source-development setup. It requires Node.js v20 and pnpm, then uses Khan Academy's clone helper before installing dependencies. The repository's `package.json` declares a different Node engine, `^24.18.0`, so the documented prerequisite and the package metadata are not aligned. This is a concrete setup issue to resolve before diagnosing application code.

Clone the repository and install its workspace dependencies with the commands shown in the README:

```bash
ka-clone git@github.com:Khan/perseus
pnpm install
```

After installation, launch the component gallery:

```bash
pnpm storybook
```

The README says this starts a server and provides a playground for the components and widgets. That is the first concrete use for a developer: inspect the existing renderer pieces before wiring a custom exercise into an application. The README does not provide a minimal application embedding example, so it does not establish a copy-and-paste production integration.

For routine development, the repository documents typechecking, tests, linting, and Storybook:

```bash
pnpm tsc -w
pnpm test
pnpm lint
```

Run those commands according to the change being made. The README does not state expected test counts or output formats.

## Changesets and catalog dependencies add release maintenance

Perseus uses changesets to manage versions across multiple npm packages. Each pull request must include a changeset file that identifies changed packages and the intended version increments. The `pnpm changeset` command generates that file. This is a meaningful upgrade concern for downstream teams because changes in one package can require coordinated version updates across the monorepo.

The repository also uses catalog dependency hashes. The README explains that when a catalog dependency such as Wonder Blocks or React changes, the hash changes and signals that affected packages should be version-bumped and republished even if their source code did not change. Developers who manually add catalog dependencies to a `package.json` are instructed to run `pnpm update-catalog-hashes`.

```bash
pnpm changeset
pnpm update-catalog-hashes
```

The pre-publish check verifies catalog hashes are current. Releases are driven through a `Version Packages` pull request. After it is approved and landed, the release script publishes new npm versions. The last push was on 2026-10-15, and the listed releases include `@khanacademy/perseus@91.0.0`, `@khanacademy/perseus-score@9.0.5`, and `@khanacademy/perseus-linter@6.1.2`, dated 2026-10-09. This indicates recent release activity, but it does not remove the need to inspect breaking changes in the relevant package.

## Perseus has a clear contribution boundary

The README explicitly says that the Perseus project is not accepting external contributions. It is released for reference and learning, but the project is not open to outside pull requests or issues. That policy makes it a different kind of adoption target from an open-source project with an active public contribution queue.

This does not prevent an engineer from studying the code, running the local development commands, or using the MIT-licensed packages under the repository's stated license. It does mean that an external team cannot expect to submit a fix through the project's normal contribution path. A team that requires an upstream feature, issue response, or community governance would need to assess that limitation before adopting the dependency.

The license is MIT. That is generally compatible with many commercial and open-source uses, subject to the actual license text and obligations, but this review does not provide legal advice. Users should preserve the required copyright and license notices and examine how Perseus packages are bundled into a product.

## A bespoke renderer is the relevant alternative

The practical alternative is a bespoke React assessment renderer built around an application's own question schema, form state, and grading service. That approach has a different boundary. It can keep the data model small, use only the fields the product needs, and connect grading directly to a backend endpoint or local answer checker.

Perseus instead offers an existing exercise format, an established renderer workflow, and separate score and linter packages. It can save work when the application needs Perseus compatibility or wants to follow Khan Academy's exercise structure. The trade-off is coupling to that format and to a multi-package TypeScript repository with its own release and dependency-management conventions.

The repository does not document a comparison with another named editor or renderer, so this is a design comparison rather than a claim that Perseus outperforms a particular product. A team should choose Perseus for format compatibility, not merely because it renders interactive widgets. If the application needs a narrow question model with no requirement for Perseus data, a custom renderer may be simpler.

## Known limits include runtime mismatch and undocumented integration details

The most visible limitation is the Node.js requirement conflict. The README lists Node.js v20, while `package.json` declares `"node": "^24.18.0"`. Because the repository is private at its root and publishes multiple workspace packages, using an unsupported runtime could affect installation, scripts, or builds. The README does not explain which version is authoritative.

The documentation also leaves important integration details unstated. It does not provide a minimal production embedding example, a complete list of supported Perseus question types, or a public API description for grading results. It says that Storybook starts a playground, but it does not explain how to deploy a Perseus application or configure persistence. Those omissions do not prove that the features are absent. They mean the repository documentation alone is insufficient for adoption planning.

External contribution is another boundary. The project is not accepting outside pull requests or issues, so defects and requested improvements may need to be handled downstream. The MIT license permits use of the code under its terms, but it does not create a promise that Khan Academy will accept patches or provide support for a particular fork.

## Conclusion

Adopt Perseus when a team specifically needs the Khan Academy exercise format, related renderer packages, and an established editing and grading system. Do not adopt it as a general-purpose assessment platform, a freely contributed community component, or a low-maintenance dependency without first confirming the Node runtime requirement, package compatibility, grading behavior, and release cadence. The repository is not archived and its last push was on 2026-10-15, but the documented Node.js v20 prerequisite conflicts with package.json, which declares "node": "^24.18.0". That mismatch must be resolved before installation is treated as reliable.

## FAQ

### What is Khan Perseus used for?

Khan Perseus is Khan Academy's exercise question editor and renderer. It takes questions in the Perseus format, presents them, allows learner interaction, and grades the learner's work.

### How do I install and run Perseus locally?

The README documents cloning the repository with `ka-clone` and running `pnpm install`, then starting `pnpm storybook`. It also lists Node.js v20 and pnpm as prerequisites, although `package.json` declares `"node": "^24.18.0"`, so the runtime requirement should be checked before installation.

### Can I contribute changes to Perseus?

No external contributions are currently accepted. The README says the project is released for reference and learning but is not open to pull requests or issues.

### How are Perseus releases versioned?

The monorepo uses changesets. A contributor runs `pnpm changeset` to create a changeset, and a `Version Packages` pull request is approved and landed to publish the affected npm packages.

## Sources

- [Khan/perseus on GitHub](https://github.com/Khan/perseus)
- [License: MIT](https://github.com/Khan/perseus/blob/main/LICENSE)
- [Project website](https://khan.github.io/perseus/)
- [README](https://github.com/Khan/perseus/blob/main/README.md)
- [Releases](https://github.com/Khan/perseus/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/khan-perseus