lightrag/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: Uses Bun (not npm/yarn)

Installation Scenarios

1. End Users (From PyPI) ✨

Command:

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:

# 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
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:

# Clone the repository
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG

# ⚠️ MUST build frontend FIRST
cd lightrag_webui
bun install
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:

# Build frontend first
cd lightrag_webui
bun install
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!

---

Error Handling

Error: WebUI Not Built (Normal Install)

╔══════════════════════════════════════════════════════════════════════════╗
║                    ⚠️  ERROR: WebUI Not Built                            ║
╚══════════════════════════════════════════════════════════════════════════╝

For normal installation (pip install .), you must build the frontend first:

    cd lightrag_webui
    bun install
    bun run build
    cd ..

Then run the installation again.

💡 TIP: For development, use editable mode instead:
   pip install -e ".[api]"

Solution:

• Build the frontend first, then install
• OR use development mode (pip install -e ".[api]")

Info: Development Mode Without Frontend

╔══════════════════════════════════════════════════════════════════════════╗
║  ℹ️  Development Mode - WebUI not built yet                             ║
╚══════════════════════════════════════════════════════════════════════════╝

You're installing in development mode. You can build the frontend later:

    cd lightrag_webui
    bun install
    bun run build

The changes will take effect immediately (symlink mode).

This is informational only - installation continues successfully.

---

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:

# 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)
│           ├── .gitkeep     # Preserves directory structure
│           ├── 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:

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: The project is configured for Bun. While npm/yarn might work, Bun is recommended per project standards.

---

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.