Convert Figma logo to code with AI

Khan logoperseus

Perseus is Khan Academy's exercise question editor and renderer.

1,458
357
1,458
58
View on GitHubView on NPM

Top Related Projects

instructure's avatar

canvas-lms

5,970

The open LMS by Instructure, Inc.

moodle's avatar

moodle

6,111

Moodle - the world's open source learning platform

Quick Overview

Perseus is an open-source framework developed by Khan Academy for building interactive exercises and assessments. It provides a set of tools and components to create engaging educational content, including multiple-choice questions, interactive graphs, and more complex problem types.

Pros

  • Highly customizable and extensible for creating various types of educational content
  • Integrates well with React and other modern web technologies
  • Supports a wide range of question types and interactive elements
  • Actively maintained by Khan Academy and the open-source community

Cons

  • Steep learning curve for developers new to the framework
  • Documentation can be sparse or outdated in some areas
  • May be overkill for simple quiz or assessment needs
  • Requires a good understanding of React and modern JavaScript

Code Examples

  1. Creating a simple multiple-choice question:
import { Perseus } from "@khanacademy/perseus";

const question = {
    question: {
        content: "What is the capital of France?",
        widgets: {},
    },
    answerArea: {
        type: "multiple-choice",
        options: {
            choices: [
                { content: "London" },
                { content: "Paris", correct: true },
                { content: "Berlin" },
                { content: "Madrid" },
            ],
        },
    },
};

const PerseusQuestion = () => (
    <Perseus
        question={question}
        onScore={(score) => console.log("Score:", score)}
    />
);
  1. Creating an interactive graph:
import { Perseus } from "@khanacademy/perseus";

const graphQuestion = {
    question: {
        content: "Plot the point (3, 2) on the graph.",
        widgets: {
            "graph1": {
                type: "interactive-graph",
                options: {
                    range: [[-5, 5], [-5, 5]],
                    labels: ["x", "y"],
                    step: [1, 1],
                    correct: { type: "point", coords: [3, 2] },
                },
            },
        },
    },
};

const GraphQuestion = () => (
    <Perseus
        question={graphQuestion}
        onScore={(score) => console.log("Score:", score)}
    />
);
  1. Creating a numeric input question:
import { Perseus } from "@khanacademy/perseus";

const numericQuestion = {
    question: {
        content: "What is 2 + 2?",
        widgets: {},
    },
    answerArea: {
        type: "input-number",
        options: {
            value: "4",
            simplify: "required",
            size: "small",
        },
    },
};

const NumericQuestion = () => (
    <Perseus
        question={numericQuestion}
        onScore={(score) => console.log("Score:", score)}
    />
);

Getting Started

To get started with Perseus:

  1. Install the package:

    npm install @khanacademy/perseus

  2. Import and use Perseus in your React application:

    import { Perseus } from "@khanacademy/perseus";
import "@khanacademy/perseus/styles/perseus-renderer.css";

function App() {
  return (
    <Perseus
      question={yourQuestionObject}
      onScore={(score) => handleScore(score)}
    />
  );
}

  3. Create question objects as shown in the examples above and pass them to the Perseus component.

  4. Customize and extend Perseus as needed for your specific educational content requirements.

Competitor Comparisons

instructure logo

canvas-lms

5,970

The open LMS by Instructure, Inc.

Pros of Canvas LMS

  • More comprehensive LMS solution with broader feature set
  • Larger community and wider adoption in educational institutions
  • Better documentation and support resources

Cons of Canvas LMS

  • More complex codebase, potentially harder to contribute to
  • Heavier system requirements for deployment
  • Less focused on interactive content creation

Code Comparison

Perseus:

const question = Perseus.renderQuestion({
  question: {
    content: "What is 2 + 2?",
    widgets: {}
  },
  answerArea: {
    calculator: false
  }
});

Canvas LMS:

class Assignment < ActiveRecord::Base
  belongs_to :course
  has_many :submissions
  validates :name, presence: true
  validates :points_possible, numericality: { greater_than_or_equal_to: 0 }
end

Summary

Perseus is a specialized library for creating interactive educational content, while Canvas LMS is a full-featured learning management system. Perseus focuses on rendering interactive questions and exercises, making it more suitable for content creators. Canvas LMS, on the other hand, provides a complete platform for course management, grading, and student interaction, making it more appropriate for educational institutions looking for an all-in-one solution.

moodle logo

moodle

6,111

Moodle - the world's open source learning platform

Pros of Moodle

  • More comprehensive learning management system (LMS) with a wider range of features
  • Larger and more active community, resulting in frequent updates and extensive plugin ecosystem
  • Supports multiple languages and is highly customizable for various educational institutions

Cons of Moodle

  • Steeper learning curve due to its complexity and extensive feature set
  • Requires more server resources and may be slower than Perseus for simpler applications
  • Can be overwhelming for users who only need basic assessment functionality

Code Comparison

Perseus (JavaScript):

const question = Perseus.renderQuestion({
  question: {
    content: "What is 2 + 2?",
    widgets: {}
  },
  answerArea: {
    calculator: false
  }
});

Moodle (PHP):

$question = new stdClass();
$question->qtype = 'numerical';
$question->name = 'Simple arithmetic';
$question->questiontext = 'What is 2 + 2?';
$question->answer = 4;

Perseus focuses on interactive, client-side rendering of questions, while Moodle's approach is more server-centric and integrated into a larger LMS framework. Perseus is better suited for lightweight, interactive math and science problems, whereas Moodle offers a complete solution for managing courses, assignments, and assessments across various subjects and educational settings.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Perseus

npm Version License

perseus logo

Perseus Exercise Renderer

Perseus is Khan Academy's exercise system. This repo contains the code needed to take a problem in the Perseus format and present it, allow interaction, and grade the result of a learner's work.

sample of Perseus in use

This repo is a constellation of sub-repos for showing exercise content. Please see individual projects in in the packages/ folder for more information about each sub-project.

Getting started

Prerequisites

Installation

To install Perseus, you need to run the following commands:

pnpm install

Installs project dependencies and tooling

Using Storybook

The components and widgets of Perseus are developed using Storybook. After you clone the project and get dependencies installed, the next step is to start storybook by running pnpm storybook. This will start a server and give you a playground to use each component.

Using Changesets

We use changesets to help manage our versioning/releases. Before pushing a new PR, add a changeset by running pnpm changeset. Commit and submit that with the PR.

Updating Dependencies

If you want to use another library in Perseus, you will need up update the dependencies. Use peerDependencies and devDependencies for dependencies that webapp is already using, such as Wonder Blocks or React.

  1. cd into to the package in which you would like to update the dependency.
cd packages/[package-name]

// Example
cd packages/perseus-editor
  1. Run the following command to update the dev dependencies and the peer dependencies.
// All dependencies
pnpm add --dev [dependency name]
// Include this too if webapp is using this dependency
pnpm add --peer [dependency name]

// Example
pnpm add --dev @khanacademy/wonder-blocks-button
pnpm add --peer @khanacademy/wonder-blocks-button

Contributing

The Perseus project is not accepting external contributions. We’re releasing the code for others to refer to and learn from, but we are not open to pull requests or issues at this time.

KA Contribution Guide

For a slightly more detailed overview, see the "Shipping a Change to Perseus" document in Confluence.

Perseus is a monorepo - a single repository that ships multiple npm packages. Generally you can treat Perseus as a single code base; things should generally just work as you expect them to during the development process. We use scripts and a tool called changesets to keep package inter-dependencies organized, release the one repo to multiple npm packages, and version changes appropriately.

Working

  1. git checkout main; git pull

  2. git checkout -b [FEATURE_BRANCH_NAME]

  3. ☢️ We don’t use deploy branches in Perseus

  4. Start a dev server

    a. pnpm start will start Storybook on localhost:6006

    b. pnpm dev will start the custom Dev UI on localhost:5173

  5. Do stuff

  6. pnpm test will run Jest/RTL tests; pnpm cypress will run Cypress tests

  7. pnpm changeset will walk you through creating a changeset (we generally stick to semver)

  8. ☢️ Empty changesets should be considered an exception to the rule and should generally be avoided

  9. git add and git commit

  10. git pull-request will walk you through creating a pull request

CI/CD aka Github

  1. When you create/update a PR, we run a series of checks against your code
    • Gerald requests reviewers (there’s a “perseus” user group that primary maintainers are in)
    • Linting/Types/Tests; checks to make sure code is properly covered
    • Check for a changeset
  2. 🍀 A snapshot release is made and can be used to check changes before merging/releasing
  3. Once checks pass and code is approved, land your changes into main using git land
  4. 🚨 main should always be releasable! Don’t land code to main that you’re not ready to ship!
  5. 🍀 Use stacked feature branches if you’re working on a big change that depends on multiple PRs

Releasing Perseus to npm

  1. Landing changes to main creates/updates a “Version Packages” PR
  2. To cut a Perseus release, approve and land the “Version Packages” PR (typically with git land)
  3. ☢️ If the CI/CD checks aren’t running, you might need to close and reopen the PR
  4. After the release script runs, you should see the new releases on the release page

Random notes

  • We use v8 to track Jest coverage. There's some old legacy code that we don't want coverage for, so we ignore that with c8 ignore. It might look like c8 isn't be used, but it's used by the v8 coverageProvider (defined in config/test/test.config.js).

License

MIT License

NPM DownloadsLast 30 Days