--- url: https://marimo-team.github.io/marimo-studio/guide/view-providers.md description: >- Write a Python package that teaches Studio a new view format, from a frontend framework to a typesetting tool. --- # Add a view provider A [view provider](../reference/glossary.md#view-provider) is a Python package that teaches Studio one [format](../reference/glossary.md#format). Install one in the notebook's environment, and its starters appear in the **New view** dialog beside the built-in ones: ![The New view dialog lists Acme report and Acme dashboard under acme-views, above the built-in starters from marimo-studio, and shows the files the selected Acme report creates](/screenshots/provider-new-view.png) This page builds `acme-views`, the package in that dialog. **Acme report** starts a plain HTML page and needs only Python. **Acme dashboard** adds a [Lit](https://lit.dev/) component bundled by Vite. ::: warning Advanced feature The view provider API is an advanced extension point. Pin `marimo-studio` to the minor line you test, such as `marimo-studio>=0.4,<0.5`. ::: ## What a provider receives and returns A provider works with the files of a [view project](../reference/glossary.md#view-project). Studio calls its methods at fixed moments and validates each record they return: | When | Studio calls | The provider receives | The provider returns | | ---------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | The **New view** dialog opens | `availability()`, `starters()` | Nothing | Whether it can run, and its starters | | Someone creates a view | `create()` | The chosen starter and the saved notebook's cells | The first files of the view project | | Source opens, or a file in the view project changes | `inspect()` | The view project | Its source documents, build inputs, hosts, and renders | | Preview, `marimo run`, or an export needs a new page | `build()` | A [build snapshot](../reference/glossary.md#build-snapshot) of the build inputs | A [page](../reference/glossary.md#page): an HTML entry file and the files it loads | | A notebook result that a render reads changes | `render()` | The render template, values as JSON, and outputs and cells as media, such as images or PDFs | [Rendered files](../reference/glossary.md#rendered-files), such as a PDF | A provider never runs the notebook. `build()` writes a page whose hosts are still empty, and Studio fills them from the session while the page is open, as [How Studio works](../how-studio-works.md#hosts-receive-results-while-the-page-is-open) describes. `render()` is the one method that receives notebook results, and they arrive already converted to JSON and images. ## Choose a pattern Every provider imports one module, `marimo_studio.view_providers`. Pick the pattern closest to your tool: | Pattern | The build | SDK pieces | Example | | ---------------------------------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | [HTML page](#write-the-provider) | copies or templates HTML | `html_sites`, `copy_inputs` | this guide's `ReportProvider` | | [Framework build](#add-a-framework-build) | bundles JavaScript with a pinned toolchain | `request.runner`, `request.work_root`, `request.cache_root` | [`deno_react`](https://github.com/marimo-team/marimo-studio/tree/main/packages/marimo-studio/src/marimo_studio/view_providers/_builtin/deno_react) | | [Command-line tool](../reference/provider-api.md#check-external-tools) | runs an installed tool that writes HTML | `probe_tool`, `copy_inputs`, `ProviderError` | [`quarto`](https://github.com/marimo-team/marimo-studio/tree/main/packages/marimo-studio/src/marimo_studio/view_providers/_builtin/quarto) | | [Rendered file](#publish-a-rendered-file) | renders files, such as a PDF, from notebook results | `Render`, `render_page`, `render()` | [`typst`](https://github.com/marimo-team/marimo-studio/tree/main/packages/marimo-studio/src/marimo_studio/view_providers/_builtin/typst) | When no pattern fits, start from the HTML page provider and replace `build()` with your tool's steps. The built-in Quarto provider also imports private `_builtin.quarto` helpers, so copy its use of the public module and keep your provider's imports to `marimo_studio.view_providers`. ## Ask a coding agent Open a coding agent in the notebook's project and paste this prompt: ```text Read https://marimo-team.github.io/marimo-studio/guide/view-providers.md and https://marimo-team.github.io/marimo-studio/reference/provider-api.md. Create the guide's acme-views package in ./acme-views for analysis.py, with the Acme report starter and the Acme dashboard starter, a Vite page with a Lit header and every output cell. Follow "Add a framework build" and the "Provider rules". Install the package with `uv add --editable ./acme-views`, run every command in "Verify the provider", and fix each failure before you stop. ``` For another framework, replace `Lit` with its name, and see [Swap Lit for a JSX framework](#swap-lit-for-a-jsx-framework). The rest of the page builds the same package by hand. ## Files in a view project Pick **Acme report** and name the view `briefing`. Studio creates the view project in the notebook's [views folder](../reference/glossary.md#views-folder), `studio/analysis/` by default: ```text studio/analysis/briefing/ view.toml names the provider that owns this view index.html the page, with one host per output cell AGENTS.md instructions for coding agents that edit this view ``` The provider writes every file except `view.toml` and decides how Studio treats it. A [source document](../reference/glossary.md#source-document) appears in Studio's Source pane for editing. A [build input](../reference/glossary.md#build-input) rebuilds the page when it changes. | File | Written by | Source document | Build input | | ------------ | --------------------------- | ------------------- | ----------- | | `index.html` | the provider, at creation | yes | yes | | `AGENTS.md` | the provider, at creation | yes | no | | `DESIGN.md` | the user or an agent, later | yes, once it exists | no | | `view.toml` | Studio | CLI and Python only | yes | `AGENTS.md` tells a coding agent which file holds the page, what the `` hosts mean, and where decisions belong. The `marimo-studio` agent skill reads it before editing a view, so ship one written for your framework. `DESIGN.md` records lasting decisions such as audience, visual direction, and interaction priorities once the view has a direction. Editing either file never rebuilds the page. ## How Studio finds the provider The package registers the provider in the `marimo_studio.view_provider` [entry point group](https://packaging.python.org/en/latest/specifications/entry-points/), the Python packaging mechanism that lets an installed package publish objects to other packages. Studio derives these names from the registration: | Name | Value | Made from | | ------------ | -------------------------------- | --------------------------------------- | | Registration | `report = "acme_views:provider"` | Entry point in the `acme-views` package | | Provider key | `acme-views/report` | Distribution name and registration name | | Starter ID | `acme-views/report:default` | Provider key and the starter key | | `view.toml` | `provider = "acme-views/report"` | Written to the view project at creation | Studio reads the entry points once per process, from its own Python environment. Restart `marimo edit` after you install a provider or change its starters. An unavailable provider's starters appear disabled with the recovery action it returned. ## Create the package From the notebook's project, create a library with [uv](https://docs.astral.sh/uv/), the Python package manager Studio uses to resolve notebook environments: ```console uv init --lib acme-views cd acme-views uv add "marimo-studio>=0.4,<0.5" ``` When the notebook's directory is a uv project, `uv init` adds `acme-views` to its workspace. Register the provider in `acme-views/pyproject.toml`: ```toml [project.entry-points."marimo_studio.view_provider"] report = "acme_views:provider" ``` ## Write the provider Replace `src/acme_views/__init__.py` with: ```python import html from pathlib import PurePosixPath from marimo_studio.view_providers import ( BuildRequest, BuildResult, InspectionRequest, BuildInput, ProjectInspection, ProviderAvailability, ProviderInfo, ProviderStarter, SourceDocument, StarterContext, StarterPlan, copy_inputs, html_sites, ) ENTRY = PurePosixPath("index.html") AGENTS = PurePosixPath("AGENTS.md") AGENTS_SOURCE = """# Acme view Studio builds this view from `index.html` with the Acme provider. - Each `` in `index.html` shows the notebook cell with that name. Move or remove hosts freely and keep their `name` values. - Keep calculations in the notebook, and layout and wording in this project. - Record audience and visual decisions in `DESIGN.md`. """ class ReportProvider: info = ProviderInfo( title="Acme report", summary="One HTML page with the notebook's output cells.", ) starter = ProviderStarter( key="default", title="Acme report", summary="Start from one HTML page with every output cell.", documents=(ENTRY, AGENTS), ) def availability(self) -> ProviderAvailability: return ProviderAvailability(True) def starters(self) -> tuple[ProviderStarter, ...]: return (self.starter,) def create(self, starter: ProviderStarter, context: StarterContext) -> StarterPlan: cells = context.output_cells hosts = "\n".join( f' ' for item in cells ) page = f""" {html.escape(context.title)}
{hosts}
""" files = {ENTRY: page.encode(), AGENTS: AGENTS_SOURCE.encode()} return StarterPlan(files=files, cell_targets=cells) def inspect(self, request: InspectionRequest) -> ProjectInspection: source = (request.project.root / ENTRY).read_bytes() sites, diagnostics = html_sites(ENTRY, source) return ProjectInspection( documents=(SourceDocument(ENTRY, "html", "edit"),), inputs=(BuildInput(ENTRY, "file"),), sites=sites, diagnostics=diagnostics, ) def build(self, request: BuildRequest) -> BuildResult: copy_inputs(request, request.staging_root) return BuildResult(ENTRY) provider = ReportProvider() ``` Each method answers one moment from [What a provider receives and returns](#what-a-provider-receives-and-returns). ### `availability()` and `starters()`: fill the New view dialog `ReportProvider` needs only Python, so `availability()` always returns `ProviderAvailability(True)`. A provider that runs an installed tool returns `probe_tool(("tool", "--version"), minimum=..., install=...)`, which reports a missing or outdated tool with your install instructions. `starters()` returns one `ProviderStarter`. Its `title` names the starter in the list, and `summary` and `documents` fill the starter's details. Add a `format`, an SVG `icon`, a `preview` screenshot, a `homepage`, and `settings` to present the starter the way the built-in ones are, as [Present a starter in the New view dialog](../reference/provider-api.md#present-a-starter-in-the-new-view-dialog) describes. Studio keeps the starter list for the life of the process. ### `create()`: write the starting files `create()` receives the saved notebook in `context.notebook` and returns every file of the new project in a `StarterPlan`. Studio writes the files. When creating the view adds Studio configuration or cell aliases to the notebook, Studio calls `create()` again with the configured notebook, so return the same plan for the same notebook. `ReportProvider` writes one `` host into `index.html` for each cell in `context.output_cells`, and adds `AGENTS.md`. `context.output_cells` lists the cells that may display output. It leaves out disabled cells and their descendants, because marimo never runs them. `context.cell_targets` supplies the name each host uses. A named cell such as `summary` keeps its name. For an unnamed cell, Studio proposes an alias such as `cell-2` and saves it in the notebook when the provider returns that target in `StarterPlan.cell_targets`. ### `inspect()`: describe the project `inspect()` returns a `ProjectInspection` with the project's documents, build inputs, and projection sites. Studio also calls it before each build. `documents` lists the Source documents, here `index.html`. Studio adds `view.toml`, `AGENTS.md`, and `DESIGN.md` itself. `inputs` lists the build inputs, so Studio rebuilds when `index.html` or `view.toml` changes. For a project with many files, `project_files(request.project)` lists every file that can affect a build. `sites` holds one projection site per ``, ``, or `mo-value` host, the spot in the page that shows the result it names. `html_sites()` records each host's line and column for Source diagnostics, and reports a malformed host. ### `build()`: publish the page `request.project.root` holds a snapshot of the build inputs, in which Studio has already marked each site's host so it can connect the host to the notebook. The `index.html` in Source keeps its original markup. `ReportProvider` copies its inputs to `request.staging_root` with `copy_inputs()`. Studio validates the staged files and publishes them as a new revision. A failed build leaves the last good revision in Preview. ## Install it and create a view From the notebook's project, install the package and check that Studio finds it: ```console uv add --editable ./acme-views uv run marimo-studio doctor acme-views/report ``` ```text available acme-views/report distribution acme-views registration report installed 0.1.0 One HTML page with the notebook's output cells. starters acme-views/report:default ``` Start `uv run marimo edit analysis.py`, open the view menu, and choose **New view**. **Acme report** appears under **From acme-views**, with **Files created** listing `index.html, AGENTS.md`. Or create the view from the CLI: ```console uv run marimo-studio view create briefing \ --target analysis.py \ --starter acme-views/report:default ``` Source shows one host per output cell in the page. Give the view a design direction by saving `studio/analysis/briefing/DESIGN.md`: ```md # Design Audience: the weekly operations review. Lead with the threshold control, then its result. ``` Studio lists `DESIGN.md` at its next inspection, such as after the next save of `index.html`: ![Source pane for the briefing view with index.html, AGENTS.md, and DESIGN.md tabs, showing marimo-cell hosts named cell-2 and summary](/screenshots/provider-source.png){width=696} Every environment that edits, builds, or exports the view needs the provider package. Publish it to a package index, or declare it as a path or Git source in the notebook's project. ## Add a framework build **Acme dashboard** bundles a Lit component with [Vite](https://vite.dev/), a frontend build tool that needs a JavaScript runtime. The machine that opens the notebook may lack Node.js, so the provider uses [Deno](https://deno.com/), a JavaScript runtime that also installs npm packages. The [`deno`](https://pypi.org/project/deno/) package on PyPI installs it into the same environment as Studio, and `deno.find_deno_bin()` returns its path. Add the dependency from `acme-views` and register a second provider: ```console uv add deno ``` ```toml [project.entry-points."marimo_studio.view_provider"] report = "acme_views:provider" vite = "acme_views.vite:provider" ``` ### Pin the dashboard's npm packages The dashboard starter copies three files from `src/acme_views/dashboard/` into every new view. `main.js` defines the Lit header: ```js import { html, LitElement } from "lit"; customElements.define( "acme-header", class extends LitElement { render() { return html`

Acme dashboard

`; } }, ); ``` `deno.json` pins Lit and Vite: ```json { "nodeModulesDir": "auto", "imports": { "lit": "npm:lit@3.3.1", "vite": "npm:vite@7.1.7" } } ``` Generate `deno.lock` beside them: ```console cd src/acme_views/dashboard uv run -- deno install --lockfile-only ``` The lockfile records the version and checksum of every package in the dependency tree. Rerun the command after you change `deno.json`. ### Write the Vite provider Create `src/acme_views/vite.py`: ```python import os from dataclasses import replace from importlib.resources import files from pathlib import Path, PurePosixPath from deno import find_deno_bin from marimo_studio.view_providers import ( BuildRequest, BuildResult, InspectionRequest, BuildInput, ProjectInspection, ProviderAvailability, ProviderCommandResult, ProviderError, ProviderInfo, ProviderStarter, SourceDocument, StarterContext, StarterPlan, copy_inputs, ) from acme_views import AGENTS, ENTRY, ReportProvider MAIN = PurePosixPath("main.js") CONFIG = PurePosixPath("deno.json") LOCK = PurePosixPath("deno.lock") TEMPLATE = files("acme_views") / "dashboard" def installed(work: Path, pattern: str) -> str: """Return the resolved paths of installed npm files that match `pattern`.""" paths = sorted((work / "node_modules" / ".deno").glob(pattern)) if not paths: raise ProviderError(f"deno install provided no {pattern}.") return ",".join(str(path.resolve()) for path in paths) def check(step: str, result: ProviderCommandResult) -> None: if result.returncode != 0: raise ProviderError( f"{step} failed with exit code {result.returncode}: " f"{result.stderr.strip()[-2000:]}", hint="Fix the error in the view's source, then build again.", code="vite-build-failed", ) class ViteProvider(ReportProvider): info = ProviderInfo( title="Acme Vite", summary="A Vite page with Lit components and the notebook's output cells.", ) starter = ProviderStarter( key="default", title="Acme dashboard", summary="Start from a Vite page with a Lit header and every output cell.", documents=(ENTRY, AGENTS, MAIN, CONFIG, LOCK), ) def availability(self) -> ProviderAvailability: try: find_deno_bin() except FileNotFoundError: return ProviderAvailability( False, reason="The deno package is not installed.", action="Install the deno package where Studio runs.", ) return ProviderAvailability(True) def create(self, starter: ProviderStarter, context: StarterContext) -> StarterPlan: plan = super().create(starter, context) page = plan.files[ENTRY].decode() page = page.replace( '
\n', '
\n \n', ).replace( " ", ' \n ', ) project_files = {**plan.files, ENTRY: page.encode()} for path in (MAIN, CONFIG, LOCK): project_files[path] = (TEMPLATE / path.name).read_bytes() return StarterPlan(files=project_files, cell_targets=plan.cell_targets) def inspect(self, request: InspectionRequest) -> ProjectInspection: inspection = super().inspect(request) return replace( inspection, documents=( *inspection.documents, SourceDocument(MAIN, "javascript", "edit"), SourceDocument(CONFIG, "json", "edit"), SourceDocument(LOCK, "json", "read"), ), inputs=( *inspection.inputs, BuildInput(MAIN, "file"), BuildInput(CONFIG, "file"), BuildInput(LOCK, "file"), ), ) def build(self, request: BuildRequest) -> BuildResult: work = request.work_root.resolve() output = request.staging_root.resolve() copy_inputs(request, work) deno = find_deno_bin() cache = {"DENO_DIR": str(request.cache_root / "deno")} result = request.runner.run( [deno, "install", "--frozen"], cwd=work, environment={**os.environ, **cache}, ) check("deno install", result) # Stop Vite's package and workspace search at the working directory. (work / "package.json").write_text('{ "private": true }\n', encoding="utf-8") (work / "pnpm-workspace.yaml").write_text("packages: []\n", encoding="utf-8") vite = [ deno, "run", "--cached-only", "--frozen", "--no-prompt", f"--allow-read={work},{output}", f"--allow-write={output}", "--allow-env", "--allow-sys=uid,osRelease", f"--allow-ffi={installed(work, '@rollup+rollup-*/**/*.node')}", f"--allow-run={installed(work, '@esbuild+*/**/esbuild*')}", "node_modules/vite/bin/vite.js", "build", "--configLoader=native", "--base", "./", "--outDir", str(output), ] check("vite build", request.runner.run(vite, cwd=work, environment=cache)) return BuildResult(ENTRY) provider = ViteProvider() ``` `ViteProvider` reuses the report provider and changes four methods: * `availability()` checks for the `deno` binary, so the **New view** dialog shows the starter's recovery action and keeps **Create view** disabled when it is missing. * `create()` copies `main.js`, `deno.json`, and `deno.lock` into the new view, and adds an `` element and a `