Developer Setup

Complete guide to setting up your development environment for contributing to Lokus or building plugins.

Prerequisites

Required Tools

Node.js and npm

Version: 18.0.0 or higher
Download from nodejs.org
Verify installation: node --version && npm --version

Rust

Latest stable version via rustup
Install from rustup.rs
Verify installation: rustc --version && cargo --version

Git

Any recent version
Download from git-scm.com
Verify installation: git --version

Platform-Specific Requirements

Windows

Visual Studio Build Tools

# Using winget
winget install Microsoft.VisualStudio.2022.BuildTools
 
# Manual download
# Visit: https://visualstudio.microsoft.com/downloads/

Required components:

C++ build tools
Windows 10/11 SDK

WebView2

# Usually pre-installed on Windows 10+
winget install Microsoft.EdgeWebView2

macOS

Xcode Command Line Tools

xcode-select --install

For iOS development (optional):

xcode-select --install
# Install full Xcode from App Store

Linux (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install -y \
    build-essential \
    curl \
    wget \
    file \
    libgtk-3-dev \
    libwebkit2gtk-4.1-dev \
    libayatana-appindicator3-dev \
    librsvg2-dev \
    patchelf \
    pkg-config

Linux (Fedora)

sudo dnf install -y \
    gcc-c++ \
    curl \
    wget \
    file \
    gtk3-devel \
    webkit2gtk4.1-devel \
    libappindicator-gtk3-devel \
    librsvg2-devel \
    patchelf \
    pkg-config

Linux (Arch)

sudo pacman -Syu
sudo pacman -S --needed \
    base-devel \
    curl \
    wget \
    file \
    gtk3 \
    webkit2gtk \
    libappindicator-gtk3 \
    librsvg \
    patchelf \
    pkg-config

Clone Repository

# Clone the repository
git clone https://github.com/lokus-ai/lokus.git
cd lokus
 
# Checkout development branch (if not working on main)
git checkout develop

Install Dependencies

Frontend Dependencies

# Install npm packages
npm install

This installs:

React and related libraries
TipTap editor
Vite build tools
Development tools (ESLint, Prettier, Vitest)

Backend Dependencies

# Rust dependencies are managed by Cargo
# They'll be downloaded on first build
cargo build --manifest-path=src-tauri/Cargo.toml

First build will take 5-10 minutes as Cargo downloads and compiles all dependencies.

Project Structure

lokus/
├── src/                      # Frontend source (React)
│   ├── editor/              # TipTap editor
│   ├── views/               # Main views
│   ├── components/          # UI components
│   ├── core/                # Core logic
│   ├── plugins/             # Plugin system
│   ├── mcp-server/          # MCP server
│   └── hooks/               # React hooks
├── src-tauri/               # Backend source (Rust)
│   ├── src/
│   │   ├── main.rs         # Entry point
│   │   ├── auth.rs         # Authentication
│   │   ├── plugins.rs      # Plugin backend
│   │   └── ...             # Other modules
│   ├── Cargo.toml          # Rust dependencies
│   └── tauri.conf.json     # Tauri config
├── packages/                # Monorepo packages
│   ├── lokus-plugin-cli/   # Plugin CLI
│   └── plugin-sdk/         # Plugin SDK
├── tests/                   # Test suites
│   ├── unit/               # Unit tests
│   ├── e2e/                # E2E tests
│   └── integration/        # Integration tests
└── docs/                    # Documentation

Configuration Files:
├── package.json            # NPM config
├── vite.config.js         # Vite config
├── vitest.config.js       # Test config
├── playwright.config.js   # E2E test config
└── tailwind.config.cjs    # Tailwind CSS

Development Workflow

Running Development Server

# Start Vite dev server + Tauri
npm run tauri dev

This will:

Start Vite dev server on port 1420
Build Rust backend in debug mode
Launch Lokus application
Enable hot module replacement (HMR)

Running Tests

Unit Tests

# Run all unit tests
npm test
 
# Watch mode
npm run test:watch
 
# With coverage
npm run test:coverage

E2E Tests

# Run E2E tests
npm run test:e2e
 
# With UI
npm run test:e2e:ui
 
# Headed mode (visible browser)
npm run test:e2e:headed

Rust Tests

# Run Rust tests
cd src-tauri
cargo test

Building for Production

Development Build

npm run build

Platform-Specific Production Build

# Windows
npm run build:windows
 
# macOS
npm run build:macos
 
# Linux
npm run build:linux
 
# All platforms
npm run build:all

Build artifacts will be in:

Windows: src-tauri/target/release/bundle/msi/ or .../nsis/
macOS: src-tauri/target/release/bundle/dmg/ or .../macos/
Linux: src-tauri/target/release/bundle/appimage/, .../deb/, or .../rpm/

Development Environment Setup

VSCode (Recommended)

Recommended Extensions

{
  "recommendations": [
    "rust-lang.rust-analyzer",
    "tauri-apps.tauri-vscode",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "vitest.explorer"
  ]
}

Workspace Settings

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "rust-analyzer.checkOnSave.command": "clippy",
  "tailwindCSS.experimental.classRegex": [
    ["clsx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
  ]
}

Environment Variables

Create .env file in project root:

# Gmail OAuth (optional)
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
 
# Development
NODE_ENV=development
RUST_LOG=debug
 
# MCP Server (optional)
MCP_SERVER_PORT=3001

Git Configuration

Set up pre-commit hooks

# Install husky
npm install --save-dev husky
 
# Initialize hooks
npx husky install

Commit message format Follow conventional commits:

feat: add new feature
fix: fix bug
docs: update documentation
style: format code
refactor: refactor code
test: add tests
chore: update dependencies

Debugging

Frontend Debugging

Chrome DevTools

Open with Ctrl+Shift+I (Windows/Linux) or Cmd+Option+I (macOS)
Available in development mode

React DevTools Install browser extension for React component inspection.

Backend Debugging

Rust Logs

# Set log level
RUST_LOG=debug npm run tauri dev
 
# Module-specific logging
RUST_LOG=lokus::auth=debug,lokus::plugins=trace npm run tauri dev

Debugger (VSCode) Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "lldb",
      "request": "launch",
      "name": "Tauri Development Debug",
      "cargo": {
        "args": [
          "build",
          "--manifest-path=./src-tauri/Cargo.toml",
          "--no-default-features"
        ]
      },
      "cwd": "${workspaceFolder}"
    }
  ]
}

Performance Profiling

React Profiler

import { Profiler } from 'react';
 
<Profiler id="Editor" onRender={onRenderCallback}>
  <Editor />
</Profiler>

Rust Profiling

# Install cargo-flamegraph
cargo install flamegraph
 
# Profile
cargo flamegraph --bin lokus

Common Development Tasks

Adding a New Feature

Create feature branch

git checkout -b feature/my-feature

Implement feature with tests
Run tests and linting

npm test
npm run lint

Build and verify

npm run build

Create pull request

Creating a Plugin

# Use plugin CLI
npm install -g lokus-plugin-cli
 
# Create plugin
lokus-plugin create my-plugin
cd my-plugin
 
# Develop
lokus-plugin dev
 
# Test
npm test
 
# Build
lokus-plugin build

See Plugin Development for details.

Working on Documentation

# Clone docs repository
git clone https://github.com/lokus-ai/lokus-docs.git
cd lokus-docs
 
# Install dependencies
npm install
 
# Start dev server
npm run dev

Troubleshooting

Build Failures

Node modules issues

rm -rf node_modules package-lock.json
npm install

Rust cache issues

cd src-tauri
cargo clean
cargo build

Platform-Specific Issues

Windows: Missing build tools

npm install --global windows-build-tools

macOS: Command line tools not found

sudo xcode-select --reset
xcode-select --install

Linux: WebKit not found

# Ubuntu/Debian
sudo apt-get install libwebkit2gtk-4.1-dev
 
# Fedora
sudo dnf install webkit2gtk4.1-devel

Performance Issues

Slow builds

Use release mode only for final builds
Enable incremental compilation (on by default)
Add to .cargo/config.toml:

[build]
incremental = true

Slow HMR

Reduce the number of files watched
Disable source maps in dev: vite.config.js

export default {
  build: {
    sourcemap: false
  }
}

Next Steps

Getting Help

GitHub Discussions: lokus-ai/lokus/discussions
Discord: Join our Discord server
Documentation: docs.lokus.ai
Email: developers@lokus.ai

Index Architecture