Views

Views are self-contained directories that produce dashboards, reports, or visualizations from your metrics data. Each view has a render.sh script as the contract — velocirepo handles discovery and orchestration, while rendering is delegated to whatever tools the view needs.

Structure

A view is any directory under views/ that contains a render.sh file:

views/
  weekly-stars/
    render.sh          # the render contract (executable)
    pyproject.toml     # Python dependencies (managed by uv)
    view.qmd           # the actual view file
  monthly-report/
    render.sh
    pyproject.toml
    app.py             # marimo notebook
  r-summary/
    render.sh
    view.R

Quick start

# Scaffold a Quarto view (creates directory with render.sh, view.qmd, pyproject.toml)
velocirepo add-view weekly-stars --framework quarto-python

# Install dependencies
velocirepo setup-views

# Render the view (rebuilds DuckDB, then runs render.sh)
velocirepo render-view weekly-stars

# Or start a live dev server (requires serve.sh in the view)
velocirepo serve-view weekly-stars

Supported frameworks

Framework	Flag	View file	render.sh runs
Quarto (Python)	`-f quarto-python`	`view.qmd`	`uv run quarto render view.qmd`
Quarto (R)	`-f quarto-r`	`view.qmd`	`ir render view.qmd`
Jupyter	`-f jupyter`	`view.ipynb`	`uv run jupyter nbconvert ...`
Marimo	`-f marimo`	`app.py`	`uv run marimo export html app.py`
R	`-f r`	`view.R`	`ir run view.R`
ggsql	`-f sql`	`view.sql`	`ggsql run view.sql`

R views (-f r and -f quarto-r) render through ir, which resolves the packages declared in the view’s frontmatter into a cached, reproducible library. Install ir once; it bootstraps renv/pak on first render, so R views need no separate setup step.

Data access

Views connect to velocirepo.duckdb by default (via a relative path embedded at scaffold time). The DB is rebuilt before every render, so views always see fresh data.

For views that need Parquet files instead, use --source parquet when scaffolding and call velocirepo export in the view’s own render.sh.

Flags for `add-view`

Flag	Description
`-f, --framework`	Framework: quarto-python, quarto-r, jupyter, marimo, r, sql (required)
`-s, --source`	Data source: duckdb (default) or parquet
`--no-uv`	Skip pyproject.toml generation

Rendering

velocirepo render-view weekly-stars  # render one view
velocirepo render-views              # render all views
velocirepo render-views reports      # render views matching a prefix

Setup and CI

# Install dependencies for all views (runs uv sync for Python views;
# R views bootstrap automatically on first render via ir)
velocirepo setup-views

In GitHub Actions:

- name: Setup views
  run: velocirepo setup-views

- name: Render views
  run: velocirepo render-views