Canonical source

This page is generated from the repository root CONTRIBUTING.md. Edit that file to change the English contributing guide (this page updates automatically).

Contributing to nexu

This file is the canonical English contributing guide. The docs site embeds it on docs.nexu.io — Contributing. 简体中文为独立译本：仓库内 docs/zh/guide/contributing.md（线上）。

Thank you for helping improve nexu. The sections below cover code, documentation, and how we review changes.

Community standards

• Code of conduct: follow CODE_OF_CONDUCT.md in all Issues, Discussions, and PRs.
• Security: do not open public issues for vulnerabilities. See SECURITY.md for how to report them; implementation notes live in specs/SECURITY.md.

Ways to contribute

• Bug reports — reproducible steps, version/OS, logs (redact secrets).
• Feature ideas — open a Discussion or Issue so maintainers can align before large PRs.
• Code — fixes and features that match the project scope.
• Docs — fixes, translations, screenshots, and clarity improvements (English + Chinese when both exist).

Before you write code

1. Search Issues and Discussions for duplicates.
2. For non-trivial changes, open an Issue first (or comment on an existing one) to agree on direction.
3. Fork the repo and work on a short-lived branch off main.

Development setup

Prerequisites

• Git
• Node.js 24+ (LTS recommended; enforced via package.json engines)
• pnpm 10.26+ (repo pins pnpm@10.26.0 via packageManager)
• npm 11+ (required for openclaw-runtime maintenance flows)

Clone and install

From the repository root (not only docs/):

git clone https://github.com/nexu-io/nexu.git
cd nexu
pnpm install

postinstall runs scripts (including OpenClaw runtime setup). The first install can take a while.

Repository layout (excerpt)

nexu/
├── apps/
│   ├── web/              # React + Ant Design dashboard
│   ├── desktop/          # Electron desktop shell
│   └── controller/       # Hono backend + OpenClaw orchestration
├── packages/shared/      # Shared Zod schemas
├── openclaw-runtime/     # Repo-local packaged OpenClaw runtime
├── scripts/              # Dev/CI scripts (launchd, probes, e2e)
├── tests/                # Vitest test suites
├── docs/                 # VitePress documentation site
└── specs/                # Design docs, product specs

Common commands

Run from the repo root unless noted.

Command	Purpose
pnpm dev	Dev stack (controller + web) with hot reload
pnpm start	Full desktop runtime (Electron + launchd services, macOS only)
pnpm stop	Stop desktop runtime (graceful SIGTERM → SIGKILL fallback)
pnpm status	Show desktop runtime status
pnpm dev:controller	Controller only
pnpm build	Production build (all packages)
pnpm typecheck	TypeScript checks across the workspace
pnpm lint	Biome check only
pnpm lint:fix	Auto-fix where safe with Biome only
pnpm format	Format/write with Biome
pnpm test	Root Vitest suite (vitest run)
pnpm check:esm-imports	ESM specifier verification (also run in CI)
pnpm dist:mac:unsigned	Build unsigned macOS desktop app for local testing

Some packages define their own scripts (for example pnpm --filter @nexu/web test:e2e for Playwright). Prefer the closest package.json to the code you change.

Note for desktop contributors: pnpm start requires macOS (uses launchd for process management). The test suite includes real launchd integration tests that only run on macOS — they're automatically skipped on other platforms. If you're contributing to desktop code, test on macOS before submitting a PR.

Code style and formatting

• Biome is the source of truth for formatting and many lint rules (biome.json).
• Pre-commit: pnpm prepare installs scripts/pre-commit into .git/hooks when possible; it runs Biome on staged *.ts, *.tsx, *.js, *.jsx, *.json files.
• Alternative hook path: git config core.hooksPath scripts (then use hooks under scripts/ as documented in scripts/pre-commit).

Run before pushing:

pnpm lint
pnpm typecheck
pnpm test

If you touched production build paths:

pnpm build
pnpm check:esm-imports

Commits

We recommend Conventional Commits-style messages so history and changelogs stay readable:

• feat: … — new feature
• fix: … — bug fix
• docs: … — documentation only
• chore: … — tooling, deps, no user-facing change
• refactor: … — behavior-preserving code change

Use the imperative mood (add, fix, not added / fixed). Split unrelated changes into separate commits when practical.

Pull requests

1. Branch from main: e.g. fix/login-validation or feat/feishu-webhook.
2. Scope — one logical change per PR; avoid drive-by reformats across the repo.
3. Title — clear, concise; match Conventional Commits if you can.
4. Description — what/why, how to test, screenshots or screen recordings for UI changes.
5. Link issues — use Fixes #123 or Closes #123 when applicable.
6. Secrets — never commit tokens, API keys, or personal credentials. Use env vars and local-only config.

Maintainers may squash or adjust commit messages on merge; keeping your branch rebased on main reduces friction.

CI expectations

• Code PRs — .github/workflows/ci.yml runs typecheck, pnpm lint, pnpm build, and pnpm check:esm-imports. Pushes that only change files under docs/ skip this workflow (paths-ignore).
• Docs PRs — .github/workflows/docs-ci.yml builds the docs site when docs/ or CONTRIBUTING.md changes.

Green CI is required before merge unless a maintainer says otherwise.

Documentation contributions

Run the docs site locally

cd docs
pnpm install   # first time only
pnpm dev

VitePress prints a local URL; use it to verify headings, links, and images.

Writing workflow

• English narrative in this guide is maintained in CONTRIBUTING.md at the repo root and included into the English docs page; edit that file for English prose, unless you are only fixing VitePress-only wiring.
• English pages under docs/en/: other guides stay in docs/en/.
• Chinese pages: docs/zh/
• New sidebar entries: update docs/.vitepress/config.ts
• When you add or substantially change a guide, keep English and Chinese in sync when both locales exist.

Paste images into Markdown

We recommend the telesoho.vscode-markdown-paste-image extension.

Workspace default (see .vscode/settings.json):

{
  "MarkdownPaste.path": "${workspaceFolder}/docs/public/assets"
}

1. Copy a screenshot to the clipboard.
2. Open the target file under docs/en/ or docs/zh/.
3. Run Markdown Paste or Cmd+Option+V (macOS) / Ctrl+Alt+V (Windows/Linux).

Link images from the site root:

![Describe the screenshot](/assets/example-image.png)

Use descriptive filenames and alt text.

Before you submit doc changes

• [ ] Both en and zh updated if the page exists in both languages
• [ ] pnpm dev preview looks correct
• [ ] New assets load from /assets/...
• [ ] Sidebar updated when adding a new page

Reviews

Reviewers care about correctness, security/privacy, maintainability, and user-facing clarity. Smaller PRs are reviewed faster.

---

Again: thank you for contributing — questions are welcome in Discussions.