Contributing to EcoPaste

English | 简体中文

Thank you for helping improve EcoPaste. This guide covers the project scope, development setup, architecture boundaries, quality checks, and contribution expectations for code and documentation changes.

Project Status

EcoPaste has entered its stable release line. Future changes should evolve the current app directly and include migrations or upgrade handling for released user data when storage, settings, or database contracts change.

Platform Scope

EcoPaste supports macOS and Windows only.

Linux is not supported, and new code, dependencies, builds, and documentation should stay focused on macOS and Windows.

Before You Change Code

Read the AGENTS.md first. It is the source of truth for architecture, platform scope, coding conventions, and quality expectations in this repository.

Respect the current working tree. Do not overwrite or roll back changes you did not make.

Use single-line Conventional Commits for commit messages, such as feat:, fix:, refactor:, or docs:.

Architecture

EcoPaste uses a Rust-first Tauri architecture:

• src-tauri/src/clipboard/ owns clipboard capture, content detection, writeback, source apps, resource storage, and loop suppression.
• src-tauri/src/db/ owns SQLite repositories, models, migrations, and FTS search.
• src-tauri/src/settings/, window/, shortcut/, tray/, menu/, autostart/, and backup/ own native behavior and persistent app state.
• src/ contains the React UI, Ant Design components, UnoCSS styling, Valtio UI/settings mirrors, i18n resources, and typed Tauri command wrappers.

The frontend calls Rust through Tauri commands and receives refresh signals through namespaced events such as clipboard://updated, settings://updated, and window://visibility.

Tech Stack

Area	Stack
Desktop shell	Tauri v2
Frontend	React 19, Ant Design 6, UnoCSS presetWind4
State	Valtio for UI state and settings mirrors
Backend	Rust, sqlx, SQLite
Build	Vite, pnpm
Quality	Biome, TypeScript, rustfmt, clippy, cargo test

Getting Started

Prerequisites

• macOS or Windows.
• Node.js 20 or newer.
• pnpm 10 or newer.
• Rust toolchain from rust-toolchain.toml (1.96.0, with rustfmt and clippy).
• Native dependencies required by Tauri v2. See the Tauri prerequisites for your operating system.
• Trellis workflow docs: Trellis documentation.

Install

pnpm install

Run in Development

pnpm tauri dev

Build

pnpm tauri build

Quality Checks

Frontend:

pnpm lint
pnpm tsc

Rust:

cd src-tauri
cargo fmt
cargo clippy -- -D warnings
cargo test

Format frontend files:

pnpm format

Repository Layout

src-tauri/
  src/
    commands/    # Tauri command entry points
    clipboard/   # clipboard read/write, capture, detection, storage
    db/          # SQLite repositories, models, migrations
    settings/    # settings model and persistence
    window/      # window state, positioning, lifecycle
    shortcut/    # global shortcuts
    tray/        # tray menu
    menu/        # item context menus
    backup/      # backup import/export
    i18n/        # Rust-side user-visible text
  migrations/
src/
  commands/      # typed Tauri invoke wrappers
  components/    # shared React components
  constants/     # mirrored cross-layer constants
  hooks/         # shared hooks
  locales/       # zh-CN and en-US translations
  pages/         # Clipboard, Preference, Preview, ContextMenu
  stores/        # Valtio UI state and settings mirrors
  types/         # TypeScript contract mirrors

Contribution Checklist

• Keep business logic, native capabilities, database access, storage, settings persistence, and platform integration in Rust unless the existing architecture clearly says otherwise.
• Keep React focused on rendering, interaction, UI state, frontend i18n, and previews.
• Mirror cross-layer constants in both Rust and src/constants/ when command names, event names, channels, or storage keys are reused across layers.
• Add migrations for released schema changes. Do not edit released migrations in place.
• Update both zh-CN and en-US locale resources for user-facing frontend text.
• Use Rust-side i18n/ for short user-visible native strings such as tray labels, native menus, and command-returned toast text.
• Run focused checks for the files you changed, and broaden validation when the change touches shared behavior or cross-layer contracts.