cherry-pick 6c05f0f8
This commit is contained in:
Raphaël MANSUY
parent
8d538ea9b3
commit
a00b4e4bc9
2 changed files with 325 additions and 3 deletions
254
docs/FrontendBuildGuide.md
Normal file
254
docs/FrontendBuildGuide.md
Normal file
|
|
@ -0,0 +1,254 @@
|
|||
# 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:**
|
||||
```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
|
||||
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
|
||||
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
|
||||
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:
|
||||
|
||||
```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)
|
||||
│ ├── .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:
|
||||
```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:** 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.
|
||||
74
setup.py
74
setup.py
|
|
@ -1,6 +1,74 @@
|
|||
# Minimal setup.py for backward compatibility
|
||||
# Primary configuration is now in pyproject.toml
|
||||
"""Minimal setup.py for backward compatibility with frontend build check"""
|
||||
|
||||
from pathlib import Path
|
||||
from setuptools import setup
|
||||
from setuptools.command.build_py import build_py
|
||||
import sys
|
||||
|
||||
setup()
|
||||
|
||||
def check_webui_exists():
|
||||
"""Check if WebUI has been built"""
|
||||
webui_index = Path("lightrag/api/webui/index.html")
|
||||
return webui_index.exists()
|
||||
|
||||
|
||||
class BuildPyCommand(build_py):
|
||||
"""Check WebUI build status before packaging/installation"""
|
||||
|
||||
def run(self):
|
||||
# Check if running in development mode
|
||||
is_develop = any(arg in sys.argv for arg in ["develop", "egg_info"])
|
||||
is_editable = "--editable" in sys.argv or "-e" in sys.argv
|
||||
|
||||
if is_develop or is_editable:
|
||||
# Development mode: friendly reminder
|
||||
if not check_webui_exists():
|
||||
print("""
|
||||
╔══════════════════════════════════════════════════════════════════════════╗
|
||||
║ ℹ️ 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).
|
||||
╚══════════════════════════════════════════════════════════════════════════╝
|
||||
""")
|
||||
else:
|
||||
# Normal installation/packaging mode: frontend build required
|
||||
if not check_webui_exists():
|
||||
print("""
|
||||
╔══════════════════════════════════════════════════════════════════════════╗
|
||||
║ ⚠️ 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]"
|
||||
|
||||
This allows you to build the frontend after installation.
|
||||
|
||||
╚══════════════════════════════════════════════════════════════════════════╝
|
||||
""")
|
||||
sys.exit(1)
|
||||
|
||||
print("✅ Proceeding with package build...")
|
||||
build_py.run(self)
|
||||
|
||||
|
||||
setup(
|
||||
cmdclass={
|
||||
"build_py": BuildPyCommand,
|
||||
}
|
||||
)
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue