Development Setup

This guide is for contributors who want to build, run, and debug Wox locally.

What you are setting up

The repository contains four parts that usually move together during development:

• wox.core/: Go backend, built-in plugins, settings, storage, packaging entrypoint
• wox.ui.flutter/wox/: Flutter desktop UI for macOS, Windows, and Linux
• wox.plugin.host.nodejs/: Node.js plugin host
• wox.plugin.host.python/: Python plugin host

The top-level Makefile wires these pieces together. In most cases you should start from the repository root instead of running each subproject manually.

Prerequisites

Install these tools first:

• Go
• Flutter
• Node.js
• pnpm
• uv

Recommended editor:

• Visual Studio Code with the checked-in workspace settings

Platform-specific requirements

macOS

• Install create-dmg if you plan to build the packaged .dmg

Windows

• Run build commands from a MINGW64 shell
• Install MinGW-w64 so native Windows runner code can compile

Linux

• Install patchelf
• Install appimagetool, or point APPIMAGE_TOOL at a local binary when building AppImage packages

Bootstrap the workspace

From the repository root:

make dev

What this does:

• checks required toolchain dependencies
• prepares embedded resource folders used by go:embed
• builds woxmr under wox.core
• builds both plugin hosts

make dev does not build the Flutter desktop app. Use it first to get the shared runtime pieces in place, then build the UI when you need a runnable app package.

Common commands

From the repository root:

make dev
make test
make smoke
make build

What they mean:

• make dev: prepare the local development environment
• make test: run the Go integration-style test suite under wox.core/test
• make smoke: run desktop smoke flows from wox.test
• make build: build the plugin hosts, Flutter UI, wox.core, and platform packaging output

If you are changing backend/plugin contracts, make build is the safest final verification because it catches cross-project drift.

Working on specific areas

Go backend (wox.core)

Typical tasks:

• plugin runtime and metadata changes
• built-in plugin behavior
• settings, persistence, routing, packaging

Useful command:

make -C wox.core build

Flutter UI (wox.ui.flutter/wox)

Typical tasks:

• launcher UI
• settings UI
• screenshot flow
• webview and preview rendering

Useful command:

make -C wox.ui.flutter/wox build

Plugin hosts

Useful commands:

make -C wox.plugin.host.nodejs build
make -C wox.plugin.host.python build

Use these when you are only changing host/runtime behavior and want a faster loop than make build.

Running the documentation site

The docs live in www/docs. To preview them locally:

cd www
pnpm install
pnpm docs:dev

To generate a production build:

cd www
pnpm docs:build

Where Wox stores local data

Wox keeps runtime data under the user's home directory:

• macOS / Linux: ~/.wox
• Windows: C:\Users\<username>\.wox

Useful subdirectories:

• ~/.wox/log/: UI and backend logs
• ~/.wox/plugins/: local plugin development directory

Troubleshooting

If make dev fails early:

• confirm go, flutter, node, pnpm, and uv are all on PATH
• on Windows, confirm you are in a MINGW64 shell instead of PowerShell or CMD
• on Linux packaging builds, confirm patchelf and appimagetool are installed

If a change compiles in one subproject but Wox still breaks end to end, run make build from the repository root. That is the fastest way to catch contract mismatches between wox.core, Flutter, and the plugin hosts.