Frontend
Open Library's frontend has evolved over many years. Today the codebase is a mix of server-rendered Templetor templates, jQuery, scattered inline styles, and a handful of Vue apps for specialized tools. The goal for 2026 is a complete visual refresh — replacing ad-hoc styles with a two-tier design token system and building new interactive UI as Lit web components.
Architecture at a Glance
Open Library's frontend has three layers:
Templates — Server-rendered HTML using Python and the Templetor template engine.
Components — Interactive UI built as Lit web components, with vanilla JavaScript for wiring up components and page-level controller logic. The codebase also has existing interactive UI in jQuery and Vue, and we're actively moving toward Lit web components as the standard.
Design tokens — CSS custom properties that define the visual language (colors, spacing, radii). Both components and templates consume these tokens, so the look and feel can be updated globally. Open Library organizes tokens into two tiers: primitives (raw values like --blue-500) and semantic tokens (contextual names like --color-link that reference primitives). Components should always use semantic tokens. See the Design Token Guide for details.
Technology Choices
Each technology in the stack exists for a specific reason:
Templetor (server-side templates)
Open Library uses Templetor, the templating engine from the web.py framework. Templates live in openlibrary/templates/ and render HTML on the server with Python data. See the Template Rendering Guide for a deep dive.
Lit (web components)
Lit is the standard for new interactive components. It produces native web components with Shadow DOM, which means:
- Styles are scoped — CSS doesn't leak in or out of the component
- Standard API — attributes, properties, events, and slots follow web platform conventions
- Small footprint — Lit adds minimal overhead on top of the web components standard
All new interactive UI should be built as Lit web components with the ol- prefix (e.g., <ol-pagination>, <ol-read-more>). See Building Components.
Vue (specialized tools only)
Vue is used for a few specialized, JavaScript-heavy tools like the librarian merge UI and reading stats. It is not the default choice for new UI. If you're building something interactive, start with Lit unless there's a specific reason Vue is better suited.
jQuery (legacy)
jQuery exists in the codebase but should not be used in new code. When modifying existing jQuery code, consider whether migrating to vanilla JS or a web component would be worthwhile.
Guides
Whether you're making your first open source contribution or proposing a new component, start at the top and go as deep as you need.
Your First Contribution
- Making Your First Frontend Change — Practical guide to finding files, running dev mode, and submitting a PR
Deep Dives
- Frontend Reference — Commands, CSS conventions, JavaScript patterns, routing, and partials
- Template Rendering Guide — Server-side rendering, the site wrapper, and Templetor syntax
- Building Components — When and how to build Lit web components and work with Vue
- Design Token Guide — The two-tier token system for colors, spacing, radii, and fonts