Monorepo Setup Guide

This guide will help you set up the WebdriverIO Desktop & Mobile monorepo for development.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js: Version 24 LTS (contributor toolchain — end-user Node range is defined per-package via engines)
```
node --version  # Should be v24.x
```
pnpm: Version 12 (installation); package.json pins the exact version
Git: For version control
```
git --version
```

Initial Setup

1. Clone the Repository

git clone https://github.com/webdriverio/desktop-mobile.git
cd desktop-mobile

2. Install Dependencies

pnpm install

This will:

Install all root-level dependencies
Install dependencies for all packages
Link workspace packages together
Set up Git hooks with Husky

3. Build All Packages

pnpm build

This builds every package in packages/, in dependency order, and Turborepo caches the results. It doesn't build the fixture apps; see e2e-testing.md for those.

4. Run Tests

pnpm turbo run test --filter=./packages/*

This runs every package's unit tests. Avoid the root pnpm test: it also runs the E2E and package tests, which need built apps.

Development Workflow

Building Packages

# Build all packages
pnpm build

# Build a specific package
pnpm --filter @wdio/electron-service build
pnpm --filter @wdio/tauri-service build

# Clean and rebuild
pnpm clean
pnpm build

Running Tests

# Run every package's tests
pnpm turbo run test --filter=./packages/*

# Run tests with coverage
pnpm test:coverage

# Run tests for specific package
pnpm --filter @wdio/electron-service test

# Run tests in watch mode
pnpm --filter @wdio/electron-service vitest

Code Quality

# Lint all packages
pnpm lint

# Lint and auto-fix
pnpm lint:fix

# Format code
pnpm format

# Type check all packages
pnpm typecheck

Development Mode

# Rebuild a package when its source changes
pnpm --filter @wdio/electron-service dev

Working with Packages

Adding a New Package

See package-structure.md for detailed guidelines.

Quick steps:

Create package directory: packages/my-package/
Copy structure from packages/electron-service/
Update package.json with your package details
Implement your code in src/
Add tests in test/
Build: pnpm --filter @wdio/my-package build (use the name from package.json)
Test: pnpm --filter @wdio/my-package test

Adding Dependencies

# Add dependency to specific package
pnpm --filter @wdio/electron-service add some-package

# Add dev dependency
pnpm --filter @wdio/electron-service add -D some-dev-package

# Add workspace dependency
pnpm --filter @wdio/electron-service add @wdio/native-utils@workspace:*

Using the Catalog

Common dependencies are managed through pnpm's catalog feature in pnpm-workspace.yaml.

To use a catalog dependency:

{
  "devDependencies": {
    "typescript": "catalog:default",
    "vitest": "catalog:default"
  }
}

Dependency Management

The project uses three catalogs to test against different versions of key dependencies:

Catalog	Purpose
`default`	Stable production versions — the reliable baseline
`next`	Latest/nightly versions — validates upcoming compatibility
`minimum`	Lowest supported versions — ensures backward compatibility

Switching Catalogs

pnpm catalog:default   # Switch all packages to stable versions
pnpm catalog:next      # Switch all packages to latest/nightly versions
pnpm catalog:minimum   # Switch all packages to lowest supported versions

Updating Catalog Versions

# Update all catalogs and dependencies interactively, then run update:tauri
pnpm update:dependencies

# Sync the Tauri fixtures to the latest stable Tauri (npm + Cargo.toml) and run cargo update
pnpm update:tauri

# Preview catalog changes without applying them
pnpm catalog:update:dry

# Target a specific catalog
pnpm catalog:update --default
pnpm catalog:update --next
pnpm catalog:update --minimum

The update process shows available updates, lets you select which to apply, updates pnpm-workspace.yaml, then runs pnpm install.

Turborepo Caching

Turborepo caches task outputs to speed up subsequent runs.

Local Cache

The local cache is stored in .turbo/ and is automatically used.

Cache Management

# Clear Turborepo cache
pnpm clean:cache

# Force rebuild (bypass cache)
pnpm build --force

Common Tasks

Clean Everything

# Clean all build artifacts and caches
pnpm clean

# Clean just the Turbo cache
pnpm clean:cache

Run CI Locally

# Run the same checks as CI
pnpm lint
pnpm typecheck
pnpm turbo run test --filter=./packages/*
pnpm build

Update Dependencies

# Update all catalogs and dependencies interactively, then run update:tauri
pnpm update:dependencies

# Sync the Tauri fixtures to the latest stable Tauri (npm + Cargo.toml) and run cargo update
pnpm update:tauri

Troubleshooting

"Cannot find module" errors

Try cleaning and reinstalling:

pnpm clean
pnpm install
pnpm build

TypeScript errors after adding dependencies

Rebuild the project:

pnpm build --force

Test failures

Make sure packages are built:

pnpm build
pnpm turbo run test --filter=./packages/*

Pre-commit hooks not running

Reinstall Husky:

pnpm prepare

IDE Setup

VS Code

Recommended extensions:

ESLint: Microsoft ESLint extension
Biome: Biome formatter
TypeScript and JavaScript Language Features: Built-in

Workspace settings (.vscode/settings.json):

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "biomejs.biome",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true,
    "source.organizeImports": true
  }
}

Platform-Specific Setup

Tauri Development

For working with Tauri packages and plugins:

Install Rust (if not already installed):

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Install Tauri CLI:

cargo install tauri-cli
# or
npm install -g @tauri-apps/cli

Build Tauri Plugin:
```
cd packages/tauri-plugin
cargo build
```

Build Tauri Test Apps:

cd fixtures/e2e-apps/tauri
pnpm tauri build

See the Tauri Plugin README for detailed setup instructions.

Dioxus Development

For working with Dioxus packages: