wehub-resource-sync
114 lines
3.7 KiB
Markdown
114 lines
3.7 KiB
Markdown
# LightRAG WebUI
|
|
|
|
LightRAG WebUI is a React-based web interface for interacting with the LightRAG system. It provides a user-friendly interface for querying, managing, and exploring LightRAG's functionalities.
|
|
|
|
## Installation
|
|
|
|
### Using Bun (recommended)
|
|
|
|
1. **Install Bun:**
|
|
|
|
If you haven't already installed Bun, follow the official documentation: [https://bun.sh/docs/installation](https://bun.sh/docs/installation)
|
|
|
|
2. **Install Dependencies:**
|
|
|
|
In the `lightrag_webui` directory, run the following command to install project dependencies:
|
|
|
|
```bash
|
|
bun install --frozen-lockfile
|
|
```
|
|
|
|
3. **Build the Project:**
|
|
|
|
Run the following command to build the project:
|
|
|
|
```bash
|
|
bun run build
|
|
```
|
|
|
|
This command will bundle the project and output the built files to the `lightrag/api/webui` directory.
|
|
|
|
### Using Node.js / npm (alternative)
|
|
|
|
If Bun is unavailable or the Bun build fails in your environment (e.g., older Linux distributions, restricted environments, or Bun version incompatibilities), you can use Node.js instead:
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
> **Note:** Tests (`bun test`) still require Bun. All other scripts (`dev`, `build`, `preview`, `lint`) work with both Bun and Node.js/npm.
|
|
|
|
## Development
|
|
|
|
- **Start the Development Server:**
|
|
|
|
```bash
|
|
# With Bun
|
|
bun run dev
|
|
|
|
# With Node.js/npm
|
|
npm run dev
|
|
```
|
|
|
|
## Script Commands
|
|
|
|
The following are some commonly used script commands defined in `package.json`:
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `bun run dev` / `npm run dev` | Starts the development server |
|
|
| `bun run build` / `npm run build` | Builds the project for production |
|
|
| `bun run lint` / `npm run lint` | Runs the linter |
|
|
| `bun run preview` / `npm run preview` | Previews the production build |
|
|
| `bun run build:bun` | Builds using Bun runtime explicitly |
|
|
| `bun test` | Runs tests (Bun only) |
|
|
|
|
## Troubleshooting
|
|
|
|
### `bun run build` fails silently or with exit code 1
|
|
|
|
This can happen due to Bun version incompatibilities or restricted environments. Try:
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
### `could not open bin metadata file` / `corrupted node_modules directory` (WSL)
|
|
|
|
```
|
|
error: could not open bin metadata file
|
|
|
|
Bun failed to remap this bin to its proper location within node_modules.
|
|
This is an indication of a corrupted node_modules directory.
|
|
```
|
|
|
|
This is a [known Bun issue](https://github.com/oven-sh/bun/issues) that surfaces on WSL. Bun installs package binaries by remapping them into `node_modules/.bin`, and that step fails when `node_modules` lives on a Windows-mounted drive (a path under `/mnt/c`, `/mnt/d`, etc.). WSL exposes those drives through the `drvfs`/`9p` filesystem, which does not support the link/metadata operations Bun relies on, so the `.bin` entries end up corrupted even right after a successful `bun install`.
|
|
|
|
Fixes, in order of preference:
|
|
|
|
1. **Move the project into the Linux filesystem.** Clone/copy LightRAG somewhere under your WSL home (e.g. `~/LightRAG`) instead of `/mnt/c/...`, then reinstall:
|
|
|
|
```bash
|
|
rm -rf node_modules
|
|
bun install --frozen-lockfile
|
|
bun run build
|
|
```
|
|
|
|
This is the recommended fix — building from a Windows-mounted path is slow and fragile regardless of this specific error.
|
|
|
|
2. **If you must stay on the mounted drive, use Node.js/npm instead of Bun** (see *Using Node.js / npm* above):
|
|
|
|
```bash
|
|
rm -rf node_modules
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
3. **Make sure Bun is up to date** (`bun upgrade`) — older Bun releases hit this remapping bug more often.
|
|
|
|
### `Cannot find package '@/lib'`
|
|
|
|
This error occurred in older versions when the Vite config used a TypeScript path alias (`@/`) that only Bun could resolve at config load time. This has been fixed by using a relative import in `vite.config.ts`.
|