README.md

Luna

Monorepo starter template powered by Bun + moonrepo, with:

• apps/web: SolidStart frontend (Vite + Nitro + Solid Router)
• apps/api: FastAPI backend with Pydantic AI
• shared UI/design-system packages under packages/*

Tech Stack

• Monorepo orchestration with moonrepo + Bun workspaces
• SolidStart frontend (apps/web) with Vite and Nitro
• FastAPI backend (apps/api) using Pydantic AI + Pydantic
• OXC + TypeScript for quality and type safety
• Toolchains pinned with proto (.prototools)

For the complete dependency list (with links), see Dependencies and Tools.

Quick Start

Run everything from the repository root unless an app README says otherwise.

# 1) Install pinned tools from .prototools (proto, moon, bun, python)
proto install

# 2) Install JS/TS dependencies
bun install

# 3) Install API Python dependencies
moon run api:setup

# 4) Verify quality checks
bun run check

Workspace Layout

apps/
  web/        # SolidStart marketing app
  api/        # FastAPI + Pydantic AI backend
packages/
  ui/         # shared UI components
  ds/         # shared design system

More details:

• Web app: apps/web/README.md
• API app: apps/api/README.md
• UI package: packages/ui/README.md
• Design system package: packages/ds/README.md

Common Commands

Root Scripts

bun run dev         # run application-layer dev tasks
bun run build       # build application-layer projects
bun run start       # start application-layer projects
bun run clean       # moon clean --all

Code Quality

bun run lint
bun run format:check
bun run typecheck
bun run check       # lint + format:check + typecheck

bun run lint:fix
bun run format
bun run fix         # lint:fix + format

App Tasks (moon)

# Web
moon run web:dev
moon run web:build
moon run web:start

# API
moon run api:setup
moon run api:dev
moon run api:start

Run Both Apps Locally

# Single command from repo root
bun run dev

# Or run in separate terminals
# Terminal 1: moon run web:dev
# Terminal 2: moon run api:dev

bun run dev uses the root script to run all app-level dev tasks together.

Web runs via Vite dev server. API runs via Uvicorn on port 8080.

Managing Running Servers

Check Running Processes

# Check if a port is in use (e.g., 8080 for API, 3000 for web)
lsof -i :8080
lsof -i :3000

# List all node/python processes running uvicorn or vite
ps aux | grep -E "(uvicorn|vite)" | grep -v grep

Kill Running Servers

# Kill process on a specific port
kill -9 <PID>

# Or use pkill to kill by process name
pkill -f "uvicorn src.main:app"   # API
pkill -f "vite"                   # Web

# Kill all node processes (if needed)
pkill -f "node"

Common Issues

• Address already in use: Port is still held by a previous process. Find and kill it with lsof -i :<port>.
• Multiple dev servers: Running bun run dev or moon run :dev starts all apps - use moon run api:dev or moon run web:dev to run a single app.

Dependencies and Tools

TypeScript and Frontend

• 🟢 Bun - JS runtime, package manager, and workspace command runner
• 🌙 Moon - task orchestration and project graph
• ⚙️ Proto - pinned toolchain management via .prototools
• ⚛️ SolidStart - full-stack app framework for apps/web
• 🧩 SolidJS - reactive UI library
• 🔀 Solid Router - routing for Solid apps
• ⚡ Vite - dev server and build tooling
• 🔥 Nitro - server runtime used by SolidStart
• 🧹 OXC (oxlint + oxfmt) - linting and formatting
• 🟦 TypeScript - static typing and project references

Python and Backend AI API

• 🐍 Python - backend runtime (version pinned in .prototools)
• 📦 uv - Python dependency and environment management
• 🚀 FastAPI - API framework
• 🤖 Pydantic AI - AI agent framework for backend AI features
• ✅ Pydantic - schema validation and data modeling
• ⚙️ pydantic-settings - environment-driven settings
• 🌐 Uvicorn - ASGI server

Configuration Map

• Tool/version pins: .prototools
• Workspace root scripts: package.json
• Moon workspace graph + VCS: .moon/workspace.yml
• Moon toolchains: .moon/toolchains.yml
• Shared app tasks: .moon/tasks/app.yml
• Shared lib tasks: .moon/tasks/lib.yml
• Root moon config: moon.yml
• TypeScript project graph: tsconfig.json
• Shared TypeScript options: tsconfig.options.json
• OXC formatter config: .oxfmtrc.json
• OXC linter config: .oxlintrc.json

Dependency Maintenance

JS/TS (Bun workspaces)

# list outdated packages across workspaces
bun outdated --recursive

# update within semver ranges
bun update --recursive

# update to latest versions
bun update --recursive --latest

Python (apps/api)

# sync dependencies from pyproject/lock
cd apps/api
uv sync

# add a dependency
uv add <package>

Toolchain Pins (.prototools)

# install or update pinned tools
proto install

# check for newer versions
proto outdated

# pin a specific version
proto pin <tool> <version>

Resources

Core Tooling

• proto docs
• moonrepo docs
• Bun docs
• uv docs

Frontend Web Apps

• SolidStart docs
• SolidJS docs
• Solid Router docs
• Vite docs
• Nitro docs

Backend AI API

• FastAPI docs
• Pydantic AI docs
• Pydantic docs
• pydantic-settings docs
• Uvicorn docs

Quality and Language

• OXC docs
• TypeScript docs