Local Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
Local development for Mailiner involves configuring a Rust-based development environment to build and run the Dioxus-powered web application. Because browsers cannot create direct TCP connections, the setup requires a WebSocket-to-TCP proxy to facilitate communication with IMAP servers.
Sources: README.md:1-12, AGENTS.md:5-7
Architecture Overview
Mailiner functions as a browser-based IMAP client cross-compiled to WebAssembly (WASM). It uses the Dioxus library for the UI and manages account settings locally via localStorage.
The diagram shows how Mailiner bypasses browser TCP limitations by routing encrypted traffic through a WebSocket proxy.
Sources: README.md:9-30, crates/mailiner-app/Cargo.toml:13-19
Development Prerequisites
Before running the application, you must install the following tools and targets:
- Rust Toolchain: Required for compiling the workspace.
- WASM Target: Add via
rustup target add wasm32-unknown-unknown. - Dioxus CLI: Install
dxto serve and build the application. - Node.js 20+: Required for running end-to-end tests.
- Proxy Server: The
ws-tcp-proxyfrom themailiner/ws-tcp-proxyrepository.
Sources: e2e/README.md:8-12, README.md:65-71
Running the Application
1. Start the WebSocket Proxy
The proxy accepts WebSocket connections and forwards payloads to the IMAP server. By default, it listens on ws://localhost:9400/proxy.
cd ws-tcp-proxy && cargo run
Sources: README.md:65-71
2. Launch Mailiner
Use the Dioxus CLI from the mailiner-rs root directory to start the development server.
| Command | Description |
|---|---|
dx serve -p mailiner-app | Starts a debug WASM build (~100 MB). |
dx serve -p mailiner-app --features dev-defaults | Prefills the onboarding form with local development defaults. |
dx build -p mailiner-app --release --web | Generates a size-optimized release bundle in target/dx/. |
Sources: README.md:73-86, crates/mailiner-app/README.md:11-21
Development Configuration
The dev-defaults feature enables prefilling the onboarding form to accelerate testing. You can set these values using environment variables during the build process.
| Environment Variable | Description |
|---|---|
MAILINER_DEV_IMAP_HOST | The address of the IMAP server. |
MAILINER_DEV_IMAP_USER | The username for IMAP authentication. |
MAILINER_DEV_PROXY_URL | The WebSocket URL (default: ws://localhost:9400/proxy). |
MAILINER_DEV_PROXY_TOKEN | The token required by the local proxy. |
Sources: README.md:88-97, crates/mailiner-app/src/components/onboarding.rs:25-45
Testing and Quality Assurance
End-to-end tests use Playwright to drive the application in a real browser against a dx serve instance.
The sequence shows the automated test flow where Playwright manages the application lifecycle.
Sources: playwright.config.ts:31-36, e2e/README.md:19-24
Running Tests
- Install dependencies:
npm installandnpx playwright install. - Execute tests:
npm run test:e2e. - UI Mode: Use
npm run test:e2e:uifor interactive debugging.
Sources: e2e/README.md:14-36, package.json:7-11
Summary of Environment Behavior
The application targets the browser via cross-compilation to WASM. Because of this, developers must ensure that any added crates support the WASM target or implement equivalent functionality directly within the Mailiner workspace. Memory efficiency techniques like lazy loading and LRU caching are prioritized to maintain performance in the browser environment.
Sources: AGENTS.md:5-13