Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

7.3 KB
Raw Blame
# Makefile for marimo - Development and build tasks
# Prerequisites:
#   - uv: for Python dependency management, testing, and building
#   - pnpm: for frontend development
#   - Node.js: for frontend development

DENO_VERSION := 2.7.14
DENO ?= uv tool run --from deno==$(DENO_VERSION) deno
DESIGN_MD_DENO_FLAGS := --no-config --no-lock --node-modules-dir=none
DESIGN_MD_READ_PATHS := frontend/src/css/app/App.css,frontend/src/css/app/Cell.css,frontend/src/core/codemirror/theme/dark.ts,frontend/src/core/codemirror/theme/light.ts,frontend/src/core/config/config-schema.ts,frontend/src/plugins/impl/data-editor/themes.ts,frontend/src/css/globals.css,frontend/src/components/editor/renderers/grid-layout/plugin.tsx,frontend/tailwind.config.cjs
DESIGN_MD_DENO_RUN_FLAGS := $(DESIGN_MD_DENO_FLAGS) --allow-read=$(DESIGN_MD_READ_PATHS) --allow-env=CI
DESIGN_MD_LINTER ?= pnpm --silent dlx @google/[email protected]

.PHONY: help
# 📖 Show available commands
help:
	@printf "\nMarimo Development Commands:\n\n"
	@awk '/^#/{c=substr($$0,3);next}c&&/^[[:alpha:]][[:alnum:]_-]+:/{printf "  \033[36m%-20s\033[0m %s\n", substr($$1,1,index($$1,":")-1),c}1{c=0}' $(MAKEFILE_LIST)
	@printf "\nRun 'make check-prereqs' and 'make install-all' to get started!\n\n"

###############
# Setup Tasks #
###############

.PHONY: install-all
# 🚀 First-time setup: Install all dependencies (frontend & Python)
install-all: fe py

.PHONY: check-prereqs
# ✓ Check if all required tools are installed
check-prereqs:
	@command -v pnpm >/dev/null 2>&1 || { echo "pnpm is required. See https://pnpm.io/installation"; exit 1; }
	@pnpm -v | grep -vq "^[0-9]\." || { echo "pnpm v12+ is required. Current version: $(shell pnpm -v)"; exit 1; }
	@command -v uv >/dev/null 2>&1 || { echo "uv is required. See https://docs.astral.sh/uv/getting-started/installation/"; exit 1; }
	@command -v node >/dev/null 2>&1 || { echo "Node.js is required. See https://nodejs.org/en/download/"; exit 1; }
	@node -v | grep -q "v2[0-9]" || { echo "Node.js v20+ is required. Current version: $(shell node -v)"; exit 1; }
	@echo "✅ All prerequisites are installed!"

.PHONY: py
# 🐍 Install Python dependencies in editable mode
py:
	@command -v uv >/dev/null 2>&1 || { echo "uv is required. See https://docs.astral.sh/uv/getting-started/installation/"; exit 1; }
	uv pip install --group=dev -e .

######################
# Development Tasks #
######################

.PHONY: fe
# 🔧 Build frontend assets
fe: marimo/_static marimo/_lsp

# 🔧 Install/build frontend if anything under frontend/
marimo/_static: $(shell find frontend/src) $(wildcard frontend/*)
	./scripts/buildfrontend.sh

# 🔧 Install/build lsp if anything in lsp/ has changed
marimo/_lsp: $(shell find packages/lsp)
	./scripts/buildlsp.sh

.PHONY: dev
dev: fe-codegen
	@echo "Starting development servers..."
	@# Start both processes, with marimo in background
	@(trap 'kill %1; exit' INT; \
	uv run marimo edit --no-token --headless /tmp --port 2718 & \
	pnpm dev)
dev-sandbox:
	@echo "Starting development servers..."
	@# Start both processes, with marimo in background
	@(trap 'kill %1; exit' INT; \
	uv run marimo edit /tmp/notebook.py --no-token --headless --sandbox & \
	pnpm dev)

#############
# Testing   #
#############

.PHONY: test
# 🧪 Run all tests (frontend, Python, end-to-end)
test: fe-test py-test e2e

.PHONY: check
# 🧹 Run all checks
check: fe-check py-check

.PHONY: fe-check
# 🧹 Check frontend (lint, typecheck)
fe-check: fe-lint fe-typecheck

.PHONY: fe-test
# 🧪 Test frontend
fe-test:
	CI=true pnpm turbo --filter @marimo-team/frontend test -- --run

.PHONY: e2e
# 🧪 Test end-to-end
e2e:
	cd frontend; pnpm playwright install; pnpm playwright test

.PHONY: visual-test
# 🖼️ Test visual baselines in the pinned Playwright container
visual-test: fe
	./scripts/run-visual-regression.sh

.PHONY: visual-update
# 🖼️ Update visual baselines in the pinned Playwright container
visual-update: fe
	./scripts/run-visual-regression.sh --update-snapshots

.PHONY: fe-lint
# 🧹 Lint frontend
fe-lint:
	cd frontend/src && uv run typos && cd - && pnpm --filter @marimo-team/frontend lint

.PHONY: fe-typecheck
# 🔍 Typecheck frontend
fe-typecheck:
	pnpm turbo --filter @marimo-team/frontend typecheck

.PHONY: fe-codegen
# 🔄 Generate frontend API
fe-codegen:
	uv run --isolated --python=3.12 --with-editable . marimo development openapi > packages/openapi/api.yaml
	pnpm run codegen
	pnpm format packages/openapi/

.PHONY: host-protocol-codegen
# Generate host protocol Python bindings
host-protocol-codegen:
	uv run --no-config --locked --script protocols/host/generate.py --include-experimental

.PHONY: host-protocol-check
# Check host model generation and portable protocol fixtures
host-protocol-check:
	@tmp=$$(mktemp -d); trap 'rm -rf "$$tmp"' EXIT; \
		uv run --no-config --locked --script protocols/host/generate.py --output-dir "$$tmp"
	uv run --no-config --locked --script protocols/host/generate.py --include-experimental --check
	uv run --locked --project protocols/host/conformance pytest -c protocols/host/conformance/pyproject.toml protocols/host/conformance protocols/host/experimental

.PHONY: fe-plugin-schema
# 🔄 Generate frontend plugin API schema
fe-plugin-schema:
	pnpm --filter @marimo-team/frontend plugins:generate-schema

.PHONY: design-md
# 🔄 Generate DESIGN.md
design-md:
	$(DENO) run $(DESIGN_MD_DENO_RUN_FLAGS) scripts/generate-design-md.ts > DESIGN.md

.PHONY: design-md-check
# 🔍 Check DESIGN.md generation
design-md-check:
	$(DENO) check $(DESIGN_MD_DENO_FLAGS) scripts/generate-design-md.ts
	$(DENO) lint --no-config scripts/generate-design-md.ts
	@tmp=$$(mktemp); \
	trap 'rm -f "$$tmp"' EXIT; \
	$(DENO) run $(DESIGN_MD_DENO_RUN_FLAGS) scripts/generate-design-md.ts > "$$tmp"; \
	diff -u DESIGN.md "$$tmp" || { \
		echo "DESIGN.md is not up to date. Run 'make design-md' to update it."; \
		exit 1; \
	}
	$(DESIGN_MD_LINTER) lint DESIGN.md

.PHONY: py-check
# 🔍 Typecheck, lint, format python
py-check:
	./scripts/pycheck.sh

.PHONY: typos
# 🔍 Check for typos
typos:
	uv run typos

.PHONY: py-test
# 🧪 Test python
py-test:
	uv run typos
	./scripts/pytest.sh --optional $(ARGS)

.PHONY: py-test-narwhals
# 🧪 Test narwhals-related tests (used externally by narwhals repo)
py-test-narwhals:
	uv run --group test pytest \
		tests/_data/ \
		tests/_plugins/ui/_impl/ \
		tests/_utils/test_narwhals_utils.py

.PHONY: py-snapshots
# 📸 Update snapshots
py-snapshots:
	uv run --group test pytest \
		tests/_server/templates/test_templates.py \
		tests/_server/api/endpoints/test_export.py \
		tests/test_api.py

##############
# Packaging  #
##############

.PHONY: wheel
# 📦 Build wheel
wheel:
	uv build


#################
# Documentation #
#################

.PHONY: docs
# 📚 Build docs
docs:
	uv run --group docs mkdocs build

.PHONY: docs-serve
# 📚 Serve docs
docs-serve:
	uv run --group docs mkdocs serve --clean

.PHONY: docs-llms
# 📚 Build docs + generate per-page .md files and the llms.txt index into site/
docs-llms: docs
	uv run --group docs python docs/scripts/html_to_markdown.py \
		--input-dir site --base-url https://docs.marimo.io
	uv run --group docs python docs/scripts/generate_llms_txt.py \
		--input-dir site --base-url https://docs.marimo.io \
		--output-index site/llms.txt

.PHONY: storybook
# 🧩 Start Storybook for UI development
storybook:
	pnpm --filter @marimo-team/frontend storybook