Skip to content

Development Setup Guide

This guide covers development environment setup, build configuration, and essential commands for Waldur HomePort development.

Essential Commands

Development

  • yarn start - Start development server (runs on port 8001)
  • yarn devcontainer - Start dev server for containerized development (binds to 0.0.0.0:8001)
  • yarn build - Create production build
  • yarn preview - Preview production build

Code Quality

  • yarn lint:check - Run ESLint checks
  • yarn lint:fix - Fix ESLint issues automatically
  • yarn format:check - Check code formatting with Prettier
  • yarn format:fix - Auto-format code with Prettier
  • yarn style:check - Check SCSS/CSS styles with Stylelint
  • yarn styles:usage report - Report Bootstrap/Metronic SCSS class usage and unused classes per partial
  • yarn styles:usage compare - Compare Bootstrap/Metronic CSS usage and selector order against baseline
  • yarn deps:unused - Check for unused dependencies with Knip
  • yarn tsgo - Typescript type check

Testing

For detailed testing standards and strategy, see Testing Standards & Strategy.

  • yarn test - Run unit tests with Vitest
  • yarn test:e2e - Run Playwright E2E tests
  • yarn test:visual - Run every Playwright project, including the visual specs (see visual-testing.md)

Dependency Management

  • yarn deps:unused - Find unused dependencies and exports with Knip
  • yarn deps:circular - Check for import cycles with oxlint import/no-cycle (config: .oxlintrc.cycles.json; @/ imports are resolved). Every static import counts, including import type / export type and a plain import of a type; only a dynamic import() does not, since lazy pages and dialogs are split off that way. oxlint reports each import that closes a cycle rather than the whole chain: follow the reported import lines from file to file to see it.

Version Management

Check current dependency versions

yarn list --depth=0

Check for outdated packages

yarn outdated

Check specific package version

yarn info <package-name> version

After updating version in package.json, install dependencies

yarn install

Update all dependencies to latest versions (use with caution)

yarn upgrade

Build System & Performance

Modern Build Configuration

  • Vite with ES modules support
  • Node.js (latest LTS) compatibility
  • Code splitting with lazy loading for all major features
  • Optimized bundle sizes and asset processing
  • Source maps for development and production debugging

Check Build Tool Versions

node --version yarn --version yarn info vite version

Performance Optimizations

  • Lazy component loading with lazyComponent utility
  • Dynamic reducer injection for Redux store
  • Automatic code splitting by route and feature
  • Optimized asset loading (images, fonts, SVG)
  • Bundle analysis and optimization tools

Key Development Tools

Code Quality & Analysis

  • Knip for unused dependency detection
  • oxlint import/no-cycle for circular dependency analysis
  • Lint-staged for pre-commit code formatting
  • CSS: SCSS compiled by Sass, Tailwind CSS v4 through @tailwindcss/vite (which adds vendor prefixes itself), and Vite's minification in production builds. There is no PostCSS configuration.

Modern Development Practices

  • ESM (ES Modules) throughout the codebase
  • TypeScript with comprehensive typing
  • Flat ESLint config format
  • Husky git hooks for automated quality checks
  • Yarn package management with lockfile integrity

Check Development Tool Versions

yarn info typescript eslint prettier husky version

Asset Management

  • SVG files processed through SVGR plugin for React components
  • Images and static assets in src/images/
  • Font files managed through Vite's asset pipeline
  • Monaco Editor for code editing capabilities
  • Sass for SCSS preprocessing

Check Asset Processing Tool Versions

Check current versions

yarn info @svgr/rollup-plugin monaco-editor sass version

Environment Variables

  • VITE_API_URL - Backend API endpoint (defaults to http://localhost:8000/)

  • VITE_LK_JWT_URL - Optional. The call token service the chat drawer sends its token requests to in development, in place of the one the homeserver's .well-known advertises: Waldur's /api/matrix/livekit on another local API, for example, when several stacks run on one machine. The drawer calls it directly (Waldur allows any origin on that path), and sends the user's OpenID token only to it and to the advertised services.

1
VITE_LK_JWT_URL=http://localhost:10790/api/matrix/livekit yarn start

The dev-server proxy settings below are read from the shell environment when vite starts, not from .env files:

  • VITE_PROXY_TARGET - Where the dev server proxies /api (defaults to VITE_API_URL)

Backend Integration

Integrates with Waldur MasterMind REST API requiring CORS configuration on the backend for local development.

API Client

  • Waldur JS Client - Custom API client for Waldur MasterMind
  • Auto-generated client with TypeScript support
  • Request/response interceptors for authentication and error handling
  • Token-based authentication with auto-refresh capabilities

Version Management

Check current version

grep "waldur-js-client" package.json

Check latest available version

yarn info waldur-js-client version

Update to latest version in package.json, then install

yarn install

Development Environment Setup

Prerequisites

  • Node.js (latest LTS - check with node --version)
  • Yarn package manager (check with yarn --version)
  • Backend Waldur MasterMind API running (typically on port 8000)

Check Prerequisites

Verify Node.js version (should be latest LTS)

node --version

Verify Yarn installation

yarn --version

Check if backend API is running

curl -I <http://localhost:8000/api/>

Initial Setup

  1. Install dependencies: yarn install
  2. Configure environment variables in .env file
  3. Start development server: yarn start
  4. Access application at <http://localhost:8001>

Docker Development

For containerized development:

  1. Use yarn devcontainer to start server bound to 1.1.1.0:8001
  2. Ensure proper network configuration for container access

IDE Configuration

  • TypeScript support with path mapping for @/* imports
  • ESLint and Prettier integration for code formatting
  • Vitest integration for test running and debugging

Browser Debugging with MCP Chrome DevTools

When debugging the frontend application using MCP Chrome DevTools:

Authentication

  • Default Staff Credentials: Username staff, password demo
  • Token Setup: Set the authentication token in localStorage:
1
localStorage.setItem('waldur/auth/token', 'your-token-here');

Testing Removed Projects

Use URLs with include_terminated=true:

1
2
http://localhost:8001/projects/{uuid}/?include_terminated=true
http://localhost:8001/projects/{uuid}/manage/?include_terminated=true&tab=general

Common MCP Commands

  • mcp__chrome-devtools__take_snapshot - Get page structure
  • mcp__chrome-devtools__evaluate_script - Run JavaScript in browser
  • mcp__chrome-devtools__list_console_messages - Check for errors
  • mcp__chrome-devtools__navigate_page - Navigate to specific URLs

Debugging Tips

  • Always set the auth token before navigating to protected pages
  • Use console.log statements in components for debugging state
  • Check network requests to verify API calls are working correctly
  • Use take_snapshot to verify UI changes are applied

Bootstrap CSS Usage & Migration

As part of the Tailwind + shadcn migration (Epic #467), scripts/bootstrap-css-usage.mjs tracks classes emitted by Bootstrap and Metronic stylesheets and ensures that dead classes do not accumulate and selector order does not regress:

  • yarn styles:usage report: Compiles each SCSS partial, extracts emitted class names, and compares them against whole tokens in tracked source files (src/, packages/, apps/). Prints per-partial used and unused class counts and names.
  • False positives: Whole-token matching treats words in comments or strings (e.g. visible, table, scroll) as a use. Therefore, a "used" count is an upper bound.
  • yarn styles:usage compare [baseline.json]: Compares current stylesheets against scripts/bootstrap-css-usage.baseline.json (runs in CI):
  • Fails if a new unused class appears in any partial.
  • Fails and prints a unified diff if selectors are added, modified, or reordered.
  • Passes when classes and selectors are removed.
  • yarn styles:usage save [baseline.json]: Saves the current compiled byte size, per-partial unused classes, and source-order selector list to the baseline JSON. Each later task in Epic #467 that removes dead rules re-runs save and commits the smaller baseline.

Translation Management

Commands

  • yarn i18n:analyze <lang> - Analyze translation quality (e.g., yarn i18n:analyze et)
  • yarn i18n:check - Check translation completeness
  • yarn i18n:validate - Validate translation file syntax
  • yarn i18n:extract - Extract translatable strings from source

Supported Languages

27 languages with specialized analyzers: Estonian (et), Russian (ru), Norwegian (nb), German (de), Spanish (es), French (fr), Italian (it), Polish (pl), Czech (cs), Lithuanian (lt), Latvian (lv), Bulgarian (bg), Slovenian (sl), Greek (el), Dutch (nl), and more.

Use yarn i18n:analyze --help to see all available languages.