Surface plugins — shenas open source

How surfaces work

Data accessThe surface component queries a local Arrow IPC endpoint that shenas exposes. All queries run against your local DuckDB — data never leaves your device.

Component modelEach surface is a Lit custom element. The element registers itself via a shenas.surfaces entry point. shenas loads it into the UI shell.

PackagingA surface plugin is a Python package that includes both the Python entry point and the compiled JS component. Build with uv build; install with shenasctl source add --local.

RenderingComponents control their own layout and charting library. Use any JS charting library — Observable Plot, Chart.js, D3 — bundled into the wheel.

Building a surface

Scaffold the component

Create a Lit custom element that extends LitElement. The component's connectedCallback fires an Arrow IPC query to fetch data from the local shenas database.

Declare the entry point

In pyproject.toml, add ashenas.surfaces entry point pointing at a Python class that returns the component name, title, and bundled JS path.

Bundle and package

Bundle the Lit component with esbuild or Vite, then include the bundle in the Python package's data files. Build the wheel withuv build.

Install and use

Install the surface wheel withshenasctl source add --local ./dist/<wheel>. The surface appears in the UI on the next page load.

Working surface examples are under plugins/surfaces/ in the repository: shenas-org/shenas Public mirror (shenas-org/shenas): Last updated 2026-05-23. Treat it as frozen; do not rely on it for current releases.