[Proposal] Update XBlock Examples, Templates, and Documentation to be React and Paragon-based

TL;DR Summary

We propose modernizing the XBlock Software Development Kit (SDK), templates, and documentation to use React and Paragon to build experiences that can leverage design tokens and accessibility improvements.

Overview

The XBlock SDK is the starter toolkit developers use to build a new type of XBlock. It's not something learners or instructors interact with directly -- it provides the basic structure and tools so a developer building a new exercise type isn't starting completely from scratch each time.

That starter toolkit hasn't been meaningfully updated since it was first released in the early 2010s, and it still assumes an older way of building the visual/interactive part of an exercise (Django templates rendering HTML on the backend), while most of the rest of Open edX has since moved to a different, more modern pattern (React on the frontend, talking to JSON-based backend endpoints).

This proposal is about modernizing that starter toolkit and its documentation so building a new XBlock the modern way is well-supported and well-documented.

This does not remove or break existing XBlocks. Existing XBlocks were already built and installed using the old template, they don't depend on the SDK's current template to keep running. This proposal only changes what a developer gets when they start a new XBlock going forward; it doesn't reach back and modify anything already built.

Problem

Most of the Open edX Platform has been rebuilt using React on the frontend and JSON-based backend endpoints. One of the long-tail elements of the platform not yet migrated are XBlocks, since they are built by myriad developers across the ecosystem. The XBlock SDK’s current state still encourages building new XBlocks using older methods. Its documentation and starter template still assume the older pattern of Django templates rendering HTML on the backend.

This has three concrete costs today:

• Higher barrier to entry. New XBlock developers have to learn an increasingly unfamiliar pattern (Django templates) instead of reusing skills they already have from the rest of the platform.

• Inconsistent look and feel. With no shared component library in the default template, every XBlock author re-implements basic UI from scratch, which is why exercises across a course can look and behave noticeably differently from each other and from the platform around them.

• Inconsistent, often minimal accessibility. Accessibility is left entirely to each XBlock author, with no shared, tested baseline. Open edX evaluates accessibility against WCAG 2.2 Level AA, and Paragon's components are built and documented with that standard in mind, so building on them gets a new XBlock much closer to that baseline by default, instead of leaving each author to work it out from scratch.

Use Cases

As an Open edX Developer, I want to be able to create modern exercise experiences without having to build a component library myself.

As a platform operator, I want my theming to be respected by installed XBlocks, rather than looking visually inconsistent with the rest of my platform.

As a learner, I want a consistent experience so that I don’t find myself confused by interface differences.

As a learner, I want exercises with baseline accessibility (and preferably better!)

Proposed Solution

We propose updating the XBlock SDK, documentation, and template to support React-based rendering and Paragon components to encourage building new XBlocks using these tools. We intend to take lessons learned from recent work implementing React-based blocks to establish best practices going forward to elevate the quality of new blocks going forward, and provide new examples for migrating existing exercises as is convenient or necessary for exercise developers.

Note that this will not affect existing blocks-- the rendering path will be entirely different, and both will be supported. XBlock structure supports this flexibility.

Implementation Plan

1. The XBlock template will be updated to use a stack of Vite (a fast frontend build tool), React, Paragon, and pnpm (safer, faster frontend package management), and use pyproject.yml with uv (fast Python package/dependency manager), replacing the older setup.py-based approach.

2. Contribute a frontend library that includes hooks, components and helper functions for XBlock development to solve common problems unique to using React to build XBlocks (loading in the theme, rendering the HTML into the right div, deriving endpoints idiomatically, etc)

3. The XBlock SDK will be updated to support hot reloading support (or have the template include hot-reloading code in the development workbench if that proves more clean) so that developers can see their changes update live instead of having to rebuild them.

4. Rewrite the XBlock development documentation to teach this pattern as the primary path, while keeping (clearly labeled) legacy documentation available for existing Django-template XBlocks.

Long-term Ownership and Maintenance Plans

We anticipate that several teams will desire this functionality, and core contributors from OpenCraft will be actively involved in its development. These contributors will continue to assist with maintenance. If needed, one or more point persons can be designated as the primary contact for this code after its release.

Contact person

Fox Piacenti (fox at http://opencraft.com )

Other Approaches Considered

We could just bump the SDK to make the build system more modern. However without including a default toolset we can expect more unneeded variance in the blocks teams develop. None of this prevents a team from using their own frontend rendering methods if they desire.

We could leave the SDK as it is now. However the technologies and methods used are so old as to frustrate new developers.