docs/FrontendBuildGuide.md

# Frontend Build Guide

## Overview

The LightRAG project includes a React-based WebUI frontend. This guide explains how frontend building works in different scenarios.

## Key Principle

- **Git Repository**: Frontend build results are **NOT** included (kept clean)
- **PyPI Package**: Frontend build results **ARE** included (ready to use)
- **Build Tool**: **Bun** is recommended, but **Node.js/npm** is fully supported as a fallback

## Installation Scenarios

### 1. End Users (From PyPI) ✨

**Command:**
```bash
pip install lightrag-hku[api]
```

**What happens:**
- Frontend is already built and included in the package
- No additional steps needed
- Web interface works immediately

---

### 2. Development Mode (Recommended for Contributors) 🔧

**Command:**
```bash
# Clone the repository
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG

# Install in editable mode (no frontend build required yet)
pip install -e ".[api]"

# Build frontend when needed (can be done anytime)
cd lightrag_webui
bun install --frozen-lockfile
bun run build
cd ..
```

**Advantages:**
- Install first, build later (flexible workflow)
- Changes take effect immediately (symlink mode)
- Frontend can be rebuilt anytime without reinstalling

**How it works:**
- Creates symlinks to source directory
- Frontend build output goes to `lightrag/api/webui/`
- Changes are immediately visible in installed package

---

### 3. Normal Installation (Testing Package Build) 📦

**Command:**
```bash
# Clone the repository
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG

# ⚠️ MUST build frontend FIRST
cd lightrag_webui
bun install --frozen-lockfile
bun run build
cd ..

# Now install
pip install ".[api]"
```

**What happens:**
- Frontend files are **copied** to site-packages
- Post-build modifications won't affect installed package
- Requires rebuild + reinstall to update

**When to use:**
- Testing complete installation process
- Verifying package configuration
- Simulating PyPI user experience

---

### 4. Creating Distribution Package 🚀

**Command:**
```bash
# Build frontend first
cd lightrag_webui
bun install --frozen-lockfile --production
bun run build
cd ..

# Create distribution packages
python -m build

# Output: dist/lightrag_hku-*.whl and dist/lightrag_hku-*.tar.gz
```

**What happens:**
- `setup.py` checks if frontend is built
- If missing, installation fails with helpful error message
- Generated package includes all frontend files

---

## GitHub Actions (Automated Release)

When creating a release on GitHub:

1. **Automatically builds frontend** using Bun
2. **Verifies** build completed successfully
3. **Creates Python package** with frontend included
4. **Publishes to PyPI** using existing trusted publisher setup

**No manual intervention required!**

---

## Quick Reference

| Scenario | Command | Frontend Required | Can Build After |
|----------|---------|-------------------|-----------------|
| From PyPI | `pip install lightrag-hku[api]` | Included | No (already installed) |
| Development | `pip install -e ".[api]"` | No | ✅ Yes (anytime) |
| Normal Install | `pip install ".[api]"` | ✅ Yes (before) | No (must reinstall) |
| Create Package | `python -m build` | ✅ Yes (before) | N/A |

---

## Bun Installation

If you don't have Bun installed:

```bash
# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# Windows
powershell -c "irm bun.sh/install.ps1 | iex"
```

Official documentation: https://bun.sh

---

## File Structure

```
LightRAG/
├── lightrag_webui/          # Frontend source code
│   ├── src/                 # React components
│   ├── package.json         # Dependencies
│   └── vite.config.ts       # Build configuration
│       └── outDir: ../lightrag/api/webui  # Build output
│
├── lightrag/
│   └── api/
│       └── webui/           # Frontend build output (gitignored)
│           ├── index.html   # Built files (after running bun run build)
│           └── assets/      # Built assets
│
├── setup.py                 # Build checks
├── pyproject.toml           # Package configuration
└── .gitignore               # Excludes lightrag/api/webui/* (except .gitkeep)
```

---

## Troubleshooting

### Q: I installed in development mode but the web interface doesn't work

**A:** Build the frontend:
```bash
cd lightrag_webui && bun run build
```

### Q: I built the frontend but it's not in my installed package

**A:** You probably used `pip install .` after building. Either:
- Use `pip install -e ".[api]"` for development
- Or reinstall: `pip uninstall lightrag-hku && pip install ".[api]"`

### Q: Where are the built frontend files?

**A:** In `lightrag/api/webui/` after running `bun run build`

### Q: Can I use npm or yarn instead of Bun?

**A:** Yes. The build scripts (`dev`, `build`, `preview`, `lint`) are runtime-agnostic and work with both Bun and Node.js/npm:
```bash
npm install
npm run build
```
Bun is recommended for speed, but npm is fully supported. Tests (`bun test`) still require Bun.

### Q: Build fails with `Cannot find package '@/lib'`

**A:** This was caused by `vite.config.ts` using a TypeScript path alias (`@/`) that only Bun could resolve at config load time. Update to the latest version where this is fixed with a relative import.

---

## Summary

✅ **PyPI users**: No action needed, frontend included
✅ **Developers**: Use `pip install -e ".[api]"`, build frontend when needed
✅ **CI/CD**: Automatic build in GitHub Actions
✅ **Git**: Frontend build output never committed

For questions or issues, please open a GitHub issue.