Exclude Frontend Build Artifacts from Git Repository

[danielaskdd]

Exclude Frontend Build Artifacts from Git Repository

Summary

This PR implements a solution to keep frontend build artifacts out of the git repository while ensuring they are included in PyPI packages. This addresses the issue of repository bloat from build artifacts while maintaining a seamless installation experience for end users.

Issue: Contributors are required to manually build the frontend after cloning the project.

Problem Statement

Previously, all frontend build results (~110 files including fonts, JavaScript bundles, CSS, and assets) were committed to the git repository. This caused:

• Repository bloat with binary and generated files
• Merge conflicts when frontend was rebuilt
• Unclear separation between source code and build artifacts
• Version control noise from frequent build output changes

Solution Overview

The solution implements a multi-layered approach:

1. Git Configuration: Frontend build artifacts are now gitignored, with only a .gitkeep placeholder tracked
2. CI/CD Integration: GitHub Actions automatically builds the frontend during the release process
3. Local Development: Smart checks guide developers based on their installation mode
4. PyPI Distribution: Published packages include the pre-built frontend for end users

Changes Made

1. GitHub Actions Workflow (.github/workflows/pypi-publish.yml)

Added frontend build steps to release-build job:

• Setup Bun runtime
• Build frontend WebUI automatically
• Verify build success before packaging
• Note: The pypi-publish job remains unchanged to preserve the existing trusted publisher configuration

# New steps added
- name: Setup Bun
- name: Build Frontend WebUI  
- name: Verify Frontend Build

2. Git Configuration (.gitignore)

Updated ignore patterns:

# Frontend build output (built during PyPI release)
lightrag/api/webui/

3. Check if frontend is built before starting server

Check if frontend artifacts exists before FASTAPI Startup:

• Check if lightrat/api/webui/index.html exists
• Exit with error message if on exits

4. Documentation (docs/FrontendBuildGuide.md)

New comprehensive guide covering:

• Installation scenarios for different user types
• Development vs. production workflows
• Troubleshooting common issues
• Quick reference table
• Bun installation instructions

4. Fix Build Failure Caused by Tailwind Config

Add @tailwindcss/typography plugin and fix Tailwind config

• Add typography plugin dependency
• Fix plugin imports in config
• Add source paths to CSS

Installation Workflows

End Users (PyPI)

pip install lightrag-hku[api]

✅ Frontend already included, works immediately

Developers (Recommended)

pip install -e ".[api]"              # Install server first

cd lightrag_webui
bun install --frozen-lockfile
bun run build                         # Build frontend before testing
cd ..

✅ Flexible workflow, changes take effect immediately

Package Testing

cd lightrag_webui
bun install --frozen-lockfile
bun run build                          # Must build frontend first
cd ..

pip install ".[api]"                  # Then install server

✅ Simulates real PyPI installation experience

GitHub Release

Fully automated: Build frontend → Create package → Publish to PyPI

Impact

Repository

• Removed: 110+ frontend build files from git tracking
• Reduced: Repository size and complexity
• Added: 1 placeholder file (.gitkeep)
• Result: Cleaner git history and diffs

Developer Experience

Must manually build frontend after cloning the project

• Flexible: Development mode allows building frontend after installation
• Clear: Helpful error messages guide correct installation approach
• Documented: Comprehensive guide for all scenarios

End Users

• No change: PyPI packages include complete, working frontend
• Better: Automated builds ensure consistency
• Reliable: No manual build steps can be forgotten

Related Issues

Closes #2204

Screenshots/Logs

lightrag-sever Error Message for Missing Frontend

================================================================================
ERROR: Frontend Not Built
================================================================================
The WebUI frontend has not been built yet.
Please build the frontend code first using the following commands:

    cd lightrag_webui
    bun install
    bun run build
    cd ..

Then restart the service.

Note: Make sure you have Bun installed. Visit https://bun.sh for installation.
================================================================================

Additional Notes

• Only the git tracking behavior has changed
• All existing frontend functionality preserved