Skip to content

Commit 34929b7

Browse files
danielaskdddanielaskdd
authored
Merge pull request #2703 from Pranavh-2004/fix-webui-build
fix(webui): make build runtime-agnostic by fixing Bun-only imports in…
2 parents 87f999c + 3d8c06a commit 34929b7

4 files changed

Lines changed: 110 additions & 56 deletions

File tree

‎docs/FrontendBuildGuide.md‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ The LightRAG project includes a React-based WebUI frontend. This guide explains
88

99
- **Git Repository**: Frontend build results are **NOT** included (kept clean)
1010
- **PyPI Package**: Frontend build results **ARE** included (ready to use)
11-
- **Build Tool**: Uses **Bun** (not npm/yarn)
11+
- **Build Tool**: **Bun** is recommended, but **Node.js/npm** is fully supported as a fallback
1212

1313
## Installation Scenarios
1414

@@ -193,7 +193,16 @@ cd lightrag_webui && bun run build
193193

194194
### Q: Can I use npm or yarn instead of Bun?
195195

196-
**A:** The project is configured for Bun. While npm/yarn might work, Bun is recommended per project standards.
196+
**A:** Yes. The build scripts (`dev`, `build`, `preview`, `lint`) are runtime-agnostic and work with both Bun and Node.js/npm:
197+
```bash
198+
npm install
199+
npm run build
200+
```
201+
Bun is recommended for speed, but npm is fully supported. Tests (`bun test`) still require Bun.
202+
203+
### Q: Build fails with `Cannot find package '@/lib'`
204+
205+
**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.
197206

198207
---
199208

‎lightrag_webui/README.md‎

Lines changed: 40 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ LightRAG WebUI is a React-based web interface for interacting with the LightRAG
44

55
## Installation
66

7+
### Using Bun (recommended)
8+
79
1. **Install Bun:**
810

911
If you haven't already installed Bun, follow the official documentation: [https://bun.sh/docs/installation](https://bun.sh/docs/installation)
@@ -26,21 +28,53 @@ LightRAG WebUI is a React-based web interface for interacting with the LightRAG
2628

2729
This command will bundle the project and output the built files to the `lightrag/api/webui` directory.
2830

31+
### Using Node.js / npm (alternative)
32+
33+
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:
34+
35+
```bash
36+
npm install
37+
npm run build
38+
```
39+
40+
> **Note:** Tests (`bun test`) still require Bun. All other scripts (`dev`, `build`, `preview`, `lint`) work with both Bun and Node.js/npm.
41+
2942
## Development
3043

3144
- **Start the Development Server:**
3245

33-
If you want to run the WebUI in development mode, use the following command:
34-
3546
```bash
47+
# With Bun
3648
bun run dev
49+
50+
# With Node.js/npm
51+
npm run dev
3752
```
3853

3954
## Script Commands
4055

4156
The following are some commonly used script commands defined in `package.json`:
4257

43-
- `bun install`: Installs project dependencies.
44-
- `bun run dev`: Starts the development server.
45-
- `bun run build`: Builds the project.
46-
- `bun run lint`: Runs the linter.
58+
| Command | Description |
59+
|---------|-------------|
60+
| `bun run dev` / `npm run dev` | Starts the development server |
61+
| `bun run build` / `npm run build` | Builds the project for production |
62+
| `bun run lint` / `npm run lint` | Runs the linter |
63+
| `bun run preview` / `npm run preview` | Previews the production build |
64+
| `bun run build:bun` | Builds using Bun runtime explicitly |
65+
| `bun test` | Runs tests (Bun only) |
66+
67+
## Troubleshooting
68+
69+
### `bun run build` fails silently or with exit code 1
70+
71+
This can happen due to Bun version incompatibilities or restricted environments. Try:
72+
73+
```bash
74+
npm install
75+
npm run build
76+
```
77+
78+
### `Cannot find package '@/lib'`
79+
80+
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`.

‎lightrag_webui/package.json‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,16 @@
44
"version": "0.0.0",
55
"type": "module",
66
"scripts": {
7-
"dev": "bunx --bun vite",
8-
"build": "bunx --bun vite build",
7+
"dev": "vite",
8+
"build": "vite build",
99
"lint": "eslint .",
10-
"preview": "bunx --bun vite preview",
10+
"preview": "vite preview",
1111
"test": "bun test",
1212
"test:watch": "bun test --watch",
1313
"test:coverage": "bun test --coverage",
14-
"dev-no-bun": "vite",
15-
"build-no-bun": "vite build --emptyOutDir",
16-
"preview-no-bun": "vite preview"
14+
"dev:bun": "bunx --bun vite",
15+
"build:bun": "bunx --bun vite build",
16+
"preview:bun": "bunx --bun vite preview"
1717
},
1818
"dependencies": {
1919
"@faker-js/faker": "^10.3.0",

‎lightrag_webui/vite.config.ts‎

Lines changed: 53 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,63 @@
1-
import { defineConfig } from 'vite'
1+
import { defineConfig, loadEnv } from 'vite'
22
import path from 'path'
3-
import { webuiPrefix } from '@/lib/constants'
43
import react from '@vitejs/plugin-react-swc'
54
import tailwindcss from '@tailwindcss/vite'
65

6+
// Use relative import instead of '@/lib/constants' path alias.
7+
// The '@' alias is configured in this file's resolve.alias and only takes effect
8+
// during bundling — Node.js cannot resolve it when loading vite.config.ts itself.
9+
// Bun resolves tsconfig paths natively, masking the issue, but Node.js does not.
10+
import { webuiPrefix } from './src/lib/constants'
11+
712
// https://vite.dev/config/
8-
export default defineConfig({
9-
plugins: [react(), tailwindcss()],
10-
resolve: {
11-
alias: {
12-
'@': path.resolve(__dirname, './src')
13+
// Use functional config form so we can call loadEnv(). import.meta.env is only
14+
// available inside Bun's runtime; Node.js leaves it undefined, crashing the build.
15+
export default defineConfig(({ mode }) => {
16+
const env = loadEnv(mode, process.cwd(), '')
17+
18+
return {
19+
plugins: [react(), tailwindcss()],
20+
resolve: {
21+
alias: {
22+
'@': path.resolve(__dirname, './src')
23+
},
24+
// Force all modules to use the same katex instance
25+
// This ensures mhchem extension registered in main.tsx is available to rehype-katex
26+
dedupe: ['katex']
1327
},
14-
// Force all modules to use the same katex instance
15-
// This ensures mhchem extension registered in main.tsx is available to rehype-katex
16-
dedupe: ['katex']
17-
},
18-
// base: import.meta.env.VITE_BASE_URL || '/webui/',
19-
base: webuiPrefix,
20-
build: {
21-
outDir: path.resolve(__dirname, '../lightrag/api/webui'),
22-
emptyOutDir: true,
23-
chunkSizeWarningLimit: 3800,
24-
rollupOptions: {
25-
// Let Vite handle chunking automatically to avoid circular dependency issues
26-
output: {
27-
// Ensure consistent chunk naming format
28-
chunkFileNames: 'assets/[name]-[hash].js',
29-
// Entry file naming format
30-
entryFileNames: 'assets/[name]-[hash].js',
31-
// Asset file naming format
32-
assetFileNames: 'assets/[name]-[hash].[ext]'
28+
// base: env.VITE_BASE_URL || '/webui/',
29+
base: webuiPrefix,
30+
build: {
31+
outDir: path.resolve(__dirname, '../lightrag/api/webui'),
32+
emptyOutDir: true,
33+
chunkSizeWarningLimit: 3800,
34+
rollupOptions: {
35+
// Let Vite handle chunking automatically to avoid circular dependency issues
36+
output: {
37+
// Ensure consistent chunk naming format
38+
chunkFileNames: 'assets/[name]-[hash].js',
39+
// Entry file naming format
40+
entryFileNames: 'assets/[name]-[hash].js',
41+
// Asset file naming format
42+
assetFileNames: 'assets/[name]-[hash].[ext]'
43+
}
3344
}
45+
},
46+
server: {
47+
proxy: env.VITE_API_PROXY === 'true' && env.VITE_API_ENDPOINTS ?
48+
Object.fromEntries(
49+
env.VITE_API_ENDPOINTS.split(',').map(endpoint => [
50+
endpoint,
51+
{
52+
target: env.VITE_BACKEND_URL || 'http://localhost:9621',
53+
changeOrigin: true,
54+
rewrite: endpoint === '/api' ?
55+
(p: string) => p.replace(/^\/api/, '') :
56+
endpoint === '/docs' || endpoint === '/redoc' || endpoint === '/openapi.json' || endpoint === '/static' ?
57+
(p: string) => p : undefined
58+
}
59+
])
60+
) : {}
3461
}
35-
},
36-
server: {
37-
proxy: import.meta.env.VITE_API_PROXY === 'true' && import.meta.env.VITE_API_ENDPOINTS ?
38-
Object.fromEntries(
39-
import.meta.env.VITE_API_ENDPOINTS.split(',').map(endpoint => [
40-
endpoint,
41-
{
42-
target: import.meta.env.VITE_BACKEND_URL || 'http://localhost:9621',
43-
changeOrigin: true,
44-
rewrite: endpoint === '/api' ?
45-
(path) => path.replace(/^\/api/, '') :
46-
endpoint === '/docs' || endpoint === '/redoc' || endpoint === '/openapi.json' || endpoint === '/static' ?
47-
(path) => path : undefined
48-
}
49-
])
50-
) : {}
5162
}
5263
})

0 commit comments

Comments
 (0)