---
url: /mosaic/get-started.md
---
# Get Started

Mosaic can be imported for use in JavaScript projects, leveraged within Jupyter notebooks, or deployed alongside a standalone DuckDB server.

## Use in JavaScript

Include the desired Mosaic libraries in your project dependencies and import them as part of your application.
For a working standalone example, take a look at the [Cross-Filter Flights 10M notebook](https://observablehq.com/@uwdata/mosaic-cross-filter-flights-10m) on Observable.

The snippet below imports vgplot, configures the coordinator to use DuckDB-WASM, and creates a plot with a single `areaY` mark to produce a time-series chart for the database table `"stocks"`.
To access the central coordinator, use the `coordinator()` method, which is exported by [Mosaic core](/core/) and also re-exported by [Mosaic vgplot](/vgplot/).

```js
import * as vg from "@uwdata/vgplot";

// configure the coordinator to use DuckDB-WASM
// creates a new database instance running in-browser
vg.coordinator().databaseConnector(vg.wasmConnector());

// load data into the database
// executes a query generated by the loadCSV helper
vg.coordinator().exec(vg.loadCSV("stocks", "stock-data.csv"));

// create an area chart, returned as an HTML element
// you can subsequently add this to your webpage
const chart = vg.plot(
  vg.areaY(vg.from("stocks"), { x: "Date", y: "Price" })
);
```

## Use in Python + Jupyter

Mosaic ships a Python API for building interactive visualizations in Jupyter and marimo notebooks. See [Mosaic vgplot in Python](/vgplot/?lang=python) and the [Jupyter widget](/jupyter/) docs to get started.

## Deploy in Observable Framework

Mosaic-powered visualizations can be in deployed dashboards or data apps published with [Observable Framework](https://observablehq.com/framework/).
For guidance on deploying Mosaic and using DuckDB to prepare data, see the [Mosaic + Framework example site](https://uwdata.github.io/mosaic-framework-example).

## Use with LLMs

The documentation is also available in an LLM-friendly plain-text format following the [llms.txt convention](https://llmstxt.org/). Point an AI assistant at these files, or paste their contents into a chat, to give it context about Mosaic:

* [`llms.txt`](/llms.txt) — an index of the documentation with links to each page.
* [`llms-full.txt`](/llms-full.txt) — the full documentation concatenated into a single file.

## Run and develop locally

To run Mosaic examples on a local DuckDB server or work on Mosaic development, make a local clone of the [Mosaic GitHub repository](https://github.com/uwdata/mosaic).

### Installation

For local installation you should have `pnpm` and `node` version 22 or higher.

* Clone https://github.com/uwdata/mosaic.
* Run `pnpm i` to install dependencies.
* Run `pnpm test` to run the test suite.

### Run Examples

After installation, you can run examples locally, using either DuckDB-WASM or a DuckDB server to load and process data.

* Run `pnpm dev` to launch a local web server and view examples. By default, the examples use DuckDB-WASM in the browser. The `rest` connector will only work if a local DuckDB server is running. For greater performance, launch and connect to a local DuckDB server as described below below.

To launch a local DuckDB server:

* Install [hatch](https://hatch.pypa.io/latest/install/), if not already present.
* Run `pnpm server` to launch the [`duckdb-server`](/server/). This runs the server in development mode, so the server will restart if you change its code.