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

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.