Environment:OpenHands OpenHands Frontend Build Environment
| Knowledge Sources | |
|---|---|
| Domains | Server_Architecture, SaaS_Infrastructure |
| Last Updated | 2026-02-11 21:00 GMT |
Overview
Node.js 22+ build environment for the OpenHands frontend (React/Vite) and the `@openhands/ui` component library.
Description
The OpenHands frontend is a React single-page application built with Vite and React Router (Remix-compatible). It uses TypeScript for type safety, Tailwind CSS for styling, and HeroUI as the UI component framework. The `@openhands/ui` shared component library is built separately with Bun as the package manager. Both require Node.js 22+ and are compiled during the Docker multi-stage build process using a Node.js 25.2 builder stage.
Usage
Use this environment for building the frontend application and for local frontend development. The production Docker image builds the frontend in a multi-stage build and serves static files via the SPAStaticFiles mount in the FastAPI application.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| Runtime | Node.js >= 22.12.0 | Required for frontend; Docker build uses Node.js 25.2 |
| Package Manager | npm >= 10.5.0 | For the frontend application |
| Package Manager | Bun >= 1.2.0 | For the openhands-ui component library (alternative: npm >= 10.0.0) |
| Build Tool | Vite >= 7.3.1 | Frontend bundler and dev server |
| Language | TypeScript >= 5.9.3 | Type-checked development |
Dependencies
Key Frontend Dependencies
- `react` >= 19.2.3
- `react-dom` >= 19.2.3
- `react-router` >= 7.6.1
- `@heroui/react` == 2.8.7
- `tailwindcss` >= 4.1.8
- `lucide-react` >= 0.562.0
- `socket.io-client` >= 4.8.3
- `@tanstack/react-query` >= 5.80.6
- `i18next` >= 25.2.1
Testing Dependencies
- `vitest` >= 4.0.14
- `@playwright/test` >= 1.57.0
- `@testing-library/react` >= 16.3.0
- `msw` >= 2.10.2 (API mocking)
Credentials
Frontend environment variables (set in `.env` or build-time):
- `VITE_BACKEND_BASE_URL`: Backend URL without protocol (default: localhost:3000)
- `VITE_BACKEND_HOST`: Backend host with port for API connections (default: 127.0.0.1:3000)
- `VITE_MOCK_API`: Enable API mocking with MSW (default: false)
- `VITE_MOCK_SAAS`: Simulate SaaS mode in development (default: false)
- `VITE_USE_TLS`: Use HTTPS/WSS for backend connections (default: false)
- `VITE_FRONTEND_PORT`: Frontend dev server port (default: 3001)
- `VITE_INSECURE_SKIP_VERIFY`: Skip TLS certificate verification (default: false)
- `VITE_GITHUB_TOKEN`: GitHub token for repository access (optional)
Quick Install
# Frontend application
cd frontend && npm install && npm run dev
# openhands-ui component library
cd openhands-ui && bun install && bun run build
# Production build
cd frontend && npm run build
Code Evidence
Node.js version constraint from `frontend/package.json:6-8`:
"engines": {
"node": ">=22.12.0"
},
"packageManager": "npm@10.5.0"
Docker multi-stage build from `containers/app/Dockerfile:1-11`:
# Build frontend
FROM node:25.2 AS frontend-builder
WORKDIR /app/frontend
COPY ./frontend/package.json ./frontend/package-lock.json ./
RUN npm ci
COPY ./frontend .
RUN npm run build
Frontend .env.sample from `frontend/.env.sample`:
VITE_BACKEND_BASE_URL="localhost:3000"
VITE_BACKEND_HOST="127.0.0.1:3000"
VITE_MOCK_API="false"
VITE_MOCK_SAAS="false"
VITE_USE_TLS="false"
VITE_FRONTEND_PORT="3001"
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `npm ERR! engine Unsupported engine` | Node.js version too old | Upgrade to Node.js >= 22.12.0 |
| `VITE_BACKEND_BASE_URL` undefined | Missing `.env` file | Copy `frontend/.env.sample` to `frontend/.env` and configure |
| WebSocket connection refused | Backend not running or wrong URL | Start backend on port 3000 or update `VITE_BACKEND_BASE_URL` |
| `Module not found: @openhands/ui` | Component library not built | Run `cd openhands-ui && bun install && bun run build` first |
Compatibility Notes
- Bun vs npm: The `@openhands/ui` library supports both Bun >= 1.2.0 and npm >= 10.0.0. Bun is preferred for faster installs.
- Vite TLS: Set `VITE_USE_TLS=true` when connecting to an HTTPS backend in development.
- SaaS Mock Mode: Set `VITE_MOCK_SAAS=true` to simulate SaaS authentication flows in local development without Keycloak.