Environment:Treeverse LakeFS Web UI Environment
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Frontend |
| Last Updated | 2026-02-08 10:00 GMT |
Overview
Node.js 18+ environment with Vite, React 18, TypeScript, and DuckDB WASM for building the lakeFS web UI.
Description
The lakeFS web UI is a React 18 single-page application built with Vite and TypeScript. It uses Material UI for components and DuckDB WASM for client-side data querying. The built assets are embedded into the Go server binary via `//go:embed` directive in `webui/content.go`. Development requires Node.js 18+ and npm for dependency management, building, linting, and testing.
Usage
Use this environment for developing or building the lakeFS web UI. It is required when modifying frontend code, running frontend tests (Vitest/Playwright), or rebuilding the embedded web assets. CI pipelines use Node.js 22.17.x for builds.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux, macOS, or Windows | Any OS with Node.js support |
| Hardware | 2+ CPU cores, 4GB+ RAM | For npm install and Vite builds |
| Disk | 1GB+ free space | For node_modules and build output |
Dependencies
System Packages
- `node` >= 18 (CI uses 22.17.x)
- `npm` (included with Node.js)
Key npm Dependencies
- `react` ^18.2.0
- `react-dom` ^18.2.0
- `@duckdb/duckdb-wasm` 1.28.0 (pinned version)
- `typescript` ^5.3.3
- `vite` ^7.3.1
- `sass` ^1.69.5
- `@vitejs/plugin-react` ^5.0.1
Dev/Test Dependencies
- `vitest` ^3.2.4
- `@testing-library/react` ^16.3.0
- `@playwright/test` ^1.40.1
- `eslint` ^9.39.2
- `prettier` ^3.7.4
Credentials
No credentials required for the web UI build environment. The built UI authenticates via the lakeFS server API at runtime.
Quick Install
cd webui
npm install
npm run build
Code Evidence
Node.js version requirement from `webui/package.json:6`:
"engines": {
"node": ">= 18"
}
DuckDB WASM pinned version from `webui/package.json` (referenced in commit `5fdf720`):
"@duckdb/duckdb-wasm": "1.28.0"
Go embed for web assets from `webui/content.go`:
//go:embed build
var Content embed.FS
CI Node.js version from `.github/workflows/node.yaml:19`:
node-version: "22.17.x"
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `engine "node" is incompatible` | Node.js version < 18 | Install Node.js 18 or newer |
| DuckDB WASM version mismatch | Unpinned or wrong duckdb-wasm version | Ensure `@duckdb/duckdb-wasm` is pinned to exactly `1.28.0` |
| `Module not found` after npm install | Stale node_modules | Delete `node_modules` and `package-lock.json`, then run `npm install` |
Compatibility Notes
- DuckDB WASM: Pinned to 1.28.0 to prevent breaking changes. Do not upgrade without testing.
- Playwright: E2E tests require browser binaries to be installed (`npx playwright install`).
- Vite: Uses ^7.3.1 which requires Node.js 18+.