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 deps:unused - Check for unused dependencies with Knip
  • yarn tsc - Typescript type check

Testing

  • yarn test - Run unit tests with Vitest
  • yarn ci:test - Run full integration test suite with Cypress
  • yarn ci:run - Run Cypress tests headless

Dependency Management

  • yarn deps:unused - Find unused dependencies and exports with Knip
  • yarn deps:circular - Check for circular dependencies with Madge

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
  • Madge for circular dependency analysis
  • Lint-staged for pre-commit code formatting
  • PostCSS with autoprefixer and cssnano for CSS optimization

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
  • Markdown content processed through vite-plugin-markdown
  • Monaco Editor for code editing capabilities
  • Sass for SCSS preprocessing

Check Asset Processing Tool Versions

Check current versions

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

Environment Variables

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 @waldur/* 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

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 gettext: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.