Skip to content

Development

RomanovCaesar edited this page Nov 3, 2026 · 5 revisions

English | 简体中文

Repository layout

The source is organized to keep the Go application buildable with the normal go build . command:

main.go                    Root executable entry point
internal/app/              Panel backend and Go tests
internal/mihomoconvert/    Mihomo sharing-link converter
web/                       Embedded HTML, CSS, JavaScript, and assets
tests/                     Browser regression scripts
scripts/                   Local run/build/release/management scripts
deploy/                    systemd and OpenRC service definitions
install.sh                 GitHub one-line Linux installer
Dockerfile, docker/        Docker image and entrypoint

The backend remains one internal Go package so its unexported validation and rendering helpers can be tested together. The frontend is a separate embedded package.

Local prerequisites

  • Go 1.24 or newer to compile; go.mod pins the toolchain to Go 1.26.10 (the crypto/x509 fix for CVE-2026-111943), which the go command downloads automatically unless GOTOOLCHAIN=local
  • Node.js for optional browser tests
  • Mihomo executable for local runtime testing
  • Playwright for the browser regression scripts

Run the application during development:

.\scripts\run.ps1

or:

./scripts/run.sh

Go tests and vet

go test ./...
go vet ./...

The main application tests cover YAML compilation, subscriptions, WARP, Multi-control, inbound synchronization, cross-panel aggregation, migration, and settings validation.

Tests that start a real Mihomo core are skipped unless MUI_TEST_CORE points to a Mihomo executable:

MUI_TEST_CORE=/path/to/mihomo go test ./...

For race testing of the networking and CLI paths:

go test -race ./... -run 'TestConfigureCLI|TestCrossSubscription|TestInboundSync|TestMesh'

Build scripts

Build Windows, a Linux amd64 binary, and run the Go test suite:

.\scripts\build.ps1

Build all published Linux Release archives:

.\scripts\build-release.ps1

The release script emits:

m-ui-linux-386.tar.gz
m-ui-linux-amd64.tar.gz
m-ui-linux-arm64.tar.gz
m-ui-linux-armv5.tar.gz
m-ui-linux-armv6.tar.gz
m-ui-linux-armv7.tar.gz
m-ui-linux-s390x.tar.gz

Each archive contains one executable named m-ui-linux-<architecture>. The release workflow also builds m-ui-windows-amd64.zip, which contains m-ui.exe.

Version injection

Builds accept MUI_VERSION. If it is not set, the scripts use a tag pointing at HEAD; otherwise they fall back to dev-<short-commit>. The linker flag is:

-ldflags="-s -w -X main.version=v0.2.0"

The value is returned by m-ui version and is also used in panel state, backup manifests, log messages, and the HTTP User-Agent.

GitHub Actions release flow

The recommended workflow is triggered by tags matching v*. It should:

  1. Check out the repository with full history.
  2. Set up Go from go.mod.
  3. Validate the tag, run go test ./..., and run go vet ./....
  4. Build the seven Linux architectures and Windows amd64 with CGO_ENABLED=0.
  5. Inject main.version using GITHUB_REF_NAME.
  6. Verify archive contents and the amd64 version output.
  7. Create a GitHub Release using contents: write.
  8. Build the Docker image and push it to ghcr.io/romanovcaesar/m-ui:<tag> (stable tags also update latest).

Use annotated semantic tags such as:

git tag -a v0.1.0 -m "m-ui v0.1.0"
git push origin v0.1.0

Prerelease tags such as v0.2.0-rc.1 should be marked as prereleases. Do not reuse an existing public version.

Frontend tests

The scripts under tests/ use Playwright to exercise Mihomo Basics, Outbound YAML editing, Multi-control, and WARP flows. Install the project test dependency in your own development environment and run the scripts with the test server running. These dependencies are not needed by the Linux runtime binary.

Interface themes

The panel, login page and subscription page have three themes, picked with the Panel Theme setting (uiTheme: shadcn, md3 or liquid; shadcn is the default). The server writes the theme into <html data-ui-theme="..."> when it serves index.html and login.html, and drops every <link> or <script> tagged data-ui-only="<other theme>" (internal/app/ui_theme.go), so a page only downloads its own theme. liquid-glass.css and the styles inside the pages are the shared base; theme-shadcn.css and theme-md3.css restyle that base and also provide the layout rules the Liquid Glass files would otherwise add. The subscription page is a Go template: it loads the Liquid Glass controls for liquid and subscription-themes.css for the other two. Fonts live in web/fonts (declared in fonts.css); icons-lucide.js and icons-material.js replace the sprite of sf-symbols.js with icons of the same sf-* ids, which a Go test checks. When you add a page or a control, check it in all three themes, in light and dark mode and at phone width.

The Liquid Glass theme imitates Apple's iOS 26 / macOS 26 Liquid Glass. LIQUID-GLASS.md in the repository describes where each control lives and how it was ported; liquid-glass-web-guide.md is a reusable write-up of the approach for other web projects.

Contribution guidelines

When changing a protocol field:

  1. Confirm the corresponding Mihomo version behavior.
  2. Update the Go model, normalization, YAML rendering, share-link generation, and UI field together.
  3. Add a focused Go regression test.
  4. Check that unsupported fields are not accidentally emitted to the core.
  5. Run go test ./... and go vet ./....
  6. Add any new interface text in all 11 languages (web/i18n.js for English and Simplified Chinese, web/i18n-locales.js for the rest); the Go tests check that every catalog is complete.
  7. Update the relevant Wiki page.

Never commit data/, generated binaries, build caches, certificates, private keys, pairing state, or local logs.

Clone this wiki locally