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:

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

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

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

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

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:

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.