[KongchangAI]
· 2 min read· 1,260 words

Datasette Lite Rewritten: Running a Full Python App in the Browser

Datasette Lite Rewritten: Running a Full Python App in the Browser

Datasette Lite is rewritten with Service Workers, letting the browser run a full Python app with URL-based configuration.

Datasette Lite is a browser port of Datasette that uses WebAssembly and Pyodide to run a Python application on the client. Author Simon Willison has released a complete rewrite based on Service Workers, solving the problem in the first version where injecting HTML via innerHTML caused JavaScript functionality to fail. The new version uses a Service Worker acting on the entire domain to intercept requests and isolates multiple tabs via the `/app/<session>/` prefix, giving each tab its own Datasette instance. URL parameters can combine plugins, databases, metadata, view state, and even SQLite versions, making a single link a complete application configuration that facilitates bug reproduction and feature demos. This architecture is not limited to Datasette—almost any Python application can adopt it, and PEP 783 and AI toolchains are further lowering the barrier to browser-side Python.

Datasette Lite Rewritten: Running a Full Python App in the Browser

Datasette Lite is a browser port of Datasette that uses WebAssembly and Pyodide to run this server-side Python application directly on the client. Author Simon Willison has just released a complete rewrite based on Service Workers, and in his words, the experience now is "almost indistinguishable from the real server-side application."

Datasette Lite interface screenshot

From "hack" to production-grade architecture

The first version of Datasette Lite was born in 2022, and the author jokingly called it a "joke"—running a server-side app in the browser is indeed a bit absurd, but it quickly proved useful. The problem was that the implementation was too clever: it ran Datasette in a Pyodide Web Worker, simulated the request stack, and then injected the generated HTML into the top-level page via innerHTML.

The direct consequence of this approach was that any JavaScript-dependent functionality stopped working. Script tags inside innerHTML don't execute, and the tricks in the Worker couldn't load additional JS and CSS files either. As a result, a large number of Datasette plugins and interactive features became useless.

The new version takes a completely different path: it registers a Service Worker that acts on the entire lite.datasette.io domain, intercepts HTTP requests for pages and resources, and responds with client-side code. The parent page creates an iframe and makes requests to addresses like /app/aa94e6851595/data/places—this is still a standard Datasette URL, just with an added /app/<session>/ prefix.

WebAssembly (Wasm) is a binary instruction format that executes efficiently in modern browsers, allowing code compiled from languages like C, C++, and Rust to run at near-native speed. Pyodide is a project that compiles the CPython interpreter to WebAssembly, enabling the complete Python runtime and its scientific computing stack (NumPy, pandas, etc.) to load and execute in the browser. Datasette Lite uses Pyodide to create an isolated Python environment on the client, thereby running Datasette—an ASGI application that originally depends on server-side I/O—without a backend server.

URL-driven customized instances

The /app/<session>/ prefix is not decorative; it exists to isolate multiple tabs. The Service Worker is shared across all tabs, and if it routed to a single Datasette instance, the plugins and parameters configured in each tab would interfere with each other. Therefore, the parent page generates a random session ID for each tab, and the Service Worker uses it to route requests to the Datasette instance running in that session's dedicated Web Worker.

This mechanism makes the URL itself a complete application configuration. Taking the official example, a single lite.datasette.io link can simultaneously:

  • ?install=datasette-maplibre installs a plugin from PyPI, and multiple install parameters can be passed repeatedly
  • ?url=... loads any SQLite database that provides open CORS headers (the author habitually hosts them on Gist)
  • ?metadata=... loads metadata.yml to add HTML descriptions to tables and the homepage
  • #/demo/capitals_and_countries%23map=0/4.2/180&color=continent uses a fragment hash to navigate to a specific view, then uses a second URL-encoded hash to control the map plugin's zoom position and coloring field

This "URL as application" idea was previously systematically explained by the author in the article "URL-addressable Pyodide Python environments." For developers, this means that reproducing bugs or demonstrating unfinished features no longer requires starting a full web server—a single link is enough. The author himself did exactly this in a discussion about a Datasette pagination bug: using ?ref=1.0a42 and ?ref=1.0a43 links to show the behavior before and after the fix, respectively.

CORS (Cross-Origin Resource Sharing) is a browser security mechanism that by default prevents web scripts from reading resources from a different origin (differing in protocol, domain, or port). The SQLite file to be loaded via the ?url= parameter is usually hosted on a third-party service (such as Gist), so the server hosting that file must return an Access-Control-Allow-Origin response header for the browser to allow Pyodide's fetch request to read its contents. This explains why the example emphasizes "a database that provides open CORS headers"—without that header, even with a correct URL, the client cannot obtain the data.

Choose any SQLite version

Another notable new feature is the ?sqlite= parameter. Datasette claims compatibility with all SQLite versions since 3.25, and SQLite has released 87 versions since then. In the past, juggling different SQLite versions and Python on a Mac was not easy, and WebAssembly happens to be the ideal vehicle: load a custom SQLite build in the browser, and once testing is done, close the tab to discard it.

The author created the datasette/pysqlite3-wasm-wheels repository, providing WebAssembly-compiled pysqlite3 wheels for 163 different SQLite versions. After passing in a version number, Datasette Lite resolves the corresponding wheel path, downloads it, and installs it into the Pyodide environment. A companion comparison tool can run the same SQL side by side, visually showing the differences in results across versions—for example, the return value of json_object nesting json_array changed type between adjacent versions.

PEP 783 is a proposal being advanced by the Python community to establish a standard binary wheel distribution format and PyPI publishing specification for WebAssembly platforms (such as Pyodide and PyScript). Currently, Python packages containing C extensions usually need to be built separately for each platform; with PEP 783, package authors can publish precompiled WebAssembly wheels just like ordinary wheels, and users can install them in browser environments without a local compilation toolchain. This is crucial for Datasette Lite's ?sqlite= parameter: the pysqlite3 wheels the author built for 163 SQLite versions currently need to be self-hosted, but in the future they can be resolved and installed directly via PyPI, greatly simplifying version management and distribution.

This approach isn't just for Datasette

The author's ambitions go beyond this. He points out that no part of Datasette Lite's implementation is specific to Datasette—almost any Python application can follow the same approach: run entirely in the browser, as a low-cost preview environment, feature demo, and bug reproduction tool.

C and Rust extensions used to be an obstacle, but today coding agents are capable of compiling them into Pyodide-compatible WebAssembly, and once PEP 783 lands, they can be published directly to PyPI. The real remaining shortcoming is databases—SQLite is no problem, while running PostgreSQL or MySQL in WebAssembly, though feasible, is still a road less traveled.

It's worth mentioning that this system was initially a research prototype generated by the author using Claude Opus, and only after becoming sufficiently familiar with the overall mechanism did he dare put it into production. From architecture diagrams to wheel builds, AI played a significant role. This may also indicate that the barrier to browser-side Python runtimes is being lowered by toolchains and agents together.

One-line Summary

Datasette Lite is rewritten with Service Workers, letting the browser run a full Python app with URL-based configuration.

Paragraph Summary

Datasette Lite is a browser port of Datasette that uses WebAssembly and Pyodide to run a Python application on the client. Author Simon Willison has released a complete rewrite based on Service Workers, solving the problem in the first version where injecting HTML via innerHTML caused JavaScript functionality to fail. The new version uses a Service Worker acting on the entire domain to intercept requests and isolates multiple tabs via the /app/<session>/ prefix, giving each tab its own Datasette instance. URL parameters can combine plugins, databases, metadata, view state, and even SQLite versions, making a single link a complete application configuration that facilitates bug reproduction and feature demos. This architecture is not limited to Datasette—almost any Python application can adopt it, and PEP 783 and AI toolchains are further lowering the barrier to browser-side Python.

Share:

Related articles