Contributing
This page expands CONTRIBUTING.md at the repository root. Read Architecture first for the shape of the code.
One-time setup
Bun 1.4.4 only. There is no Node, npm or npx anywhere in the workflow. From the repository root:
cd core && bun install --frozen-lockfilecd word/sidebar && bun install --frozen-lockfile # the fuzz tests import word/sidebar/srccd gpui-ui && bun install --frozen-lockfilebun core/scripts/fetch-zotero-vendor.ts # Zotero's translators and framework, pinned commitsmkdir -p core/vendor/fulltext-wasm && : > core/vendor/fulltext-wasm/fulltext.wasm # empty placeholderThe placeholder lets the module graph load; tests that need the real engine skip. Anything beyond this (the Rust library, the document worker, the reader, the executable, the installer) is covered in Building. You only need it when you work on the part that uses it.
Run the app against a copy of a library, never the real one, because the core writes to its database:
cd gpui-uiZN_DB=C:/path/to/library-COPY.sqlite bun src/main.tsxBefore you push
Run the checks for every project you touched. CI runs all of them on every push.
cd core && bun check && bun test --timeout 30000cd gpui-ui && bun check && bun test --timeout 30000cd word/sidebar && bun check && bun testdotnet build word/addin/ZoteroNextWord.csproj -c Release -nologo -v q -o "$TEMP/addin-out" # if you touched word/addincd connector-host && bun run build && bun test # if you touched connector-host or core/src/connectorNotes:
- Typecheck with
bun check, nottscorbunx tsc. - Pass
-otodotnet buildso the build stays out ofword/dist, which can be an installed add-in on a developer machine. - If you change anything under
core/src/connectororcore/src/db.ts, rebuild the connector host: it embeds them. - If you touch a parser or anything that reads untrusted data, run the long fuzz suite once:
cd core && ZN_FUZZ_RUNS=5000 bun test test/fuzz. See Testing. - A change to layout is checked with the headless screenshot scripts in
gpui-ui/scripts/, not by tests.
Code conventions
These are what the code does today; there is no formatter or linter configuration in the repository, so match the surrounding file.
- TypeScript and TSX in
core,gpui-ui,word/sidebarandconnector-hostare indented with tabs. The C# inword/addinuses four spaces. - Bun for everything:
bun:sqlitefor SQLite,Bun.servefor HTTP,bun testfor tests,bun checkfor types. - Files start with a comment saying what the file is for and any non-obvious constraint; follow that.
- GPUIX facts the UI code relies on (from
gpui-ui/src/features/kit.tsx): every<text>has an explicit colour (useTxt), a<text>has one child (pass a template string), and there is nodisplay: none. Icons are lucide kebab-case names. - Do not hard-code a user name or a home folder. Locations come from the per-OS folders in
core/src/platform-dirs.ts(do not assume%APPDATA%), the home folder or an environment variable (core/src/library-location.tsis the model). Code must also run on Linux and macOS:coreis tested on Linux in CI, and aprocess.platformbranch needs both sides. - Do not add personal data, tokens or keys. The update private key lives outside the repository and the release script refuses a path inside it.
- Tests use temporary folders and libraries and never your real library or the network.
Where things live
| You want to change | Look in |
|---|---|
| A screen, dialog or control | gpui-ui/src/ (App.tsx, Sidebar.tsx, itempane/, cards/, table/, reader/, settings/, features/) |
| Shell extension points | gpui-ui/src/registry.ts |
| Database, migrations | core/src/db.ts, core/src/migrations/; see Database |
| An API route | core/src/api.ts or the feature’s api.ts; see HTTP API |
| Importers and exporters | core/src/io/, core/src/import/, core/src/zport/ |
| Translators | core/src/translate/; see Translators |
| Citations | core/src/cite/ |
| Sync | core/src/sync/ (local Zotero), core/src/websync/ (zotero.org) |
| PDF rendering | gpui-ui/native/pdf/ and gpui-ui/src/reader/pdf.ts |
| Per-OS code (web view, display, printing) | gpui-ui/src/webview/ (win32.ts, x11.ts, cocoa.ts), gpui-ui/src/shell/, gpui-ui/src/reader/printGtk.ts, printMac.ts; see Architecture |
| Build, package, release | gpui-ui/scripts/ (including appimage.ts and dmg.ts), gpui-ui/installer/, .github/workflows/; see Building, Releasing |
| The Word add-in | word/addin/ (C#), word/sidebar/ (TypeScript) |
| Documentation | docs/user-guide/, docs/developer-guide/ |
Add a setting
Settings are data. gpui-ui/src/settings/registry.ts holds a list of sections and a list of SettingDef rows; the Settings page renders and searches them.
-
Persist the value.
gpui-ui/src/shell/prefs.tsexposespersisted(key, default, validator), which returns a signal pair stored in the UI-state file. Look atgpui-ui/src/settings/generalPrefs.ts:import { isBool, persisted } from "../shell/prefs";export const [autoTag, setAutoTag] = persisted<boolean>("general.autoTag", true, isBool);A feature uses
persistedre-exported fromgpui-ui/src/features/prefs.ts, with keys namespacedfeatures.<feature>.<name>. A setting that must be shared with other programs or survive a library change belongs in the core (an API route and the database) instead. -
Add a row to an existing section in
gpui-ui/src/settings/defs/*.tsx(appearance, general, reader, sync, files, integrations, system, updates), or register one from a feature:registerSettings([{id: "system.example", section: "system", group: "Diagnostics",label: "Example", description: "One sentence for the user.",keywords: ["synonyms", "the user might search"],control: () => <Toggle checked={autoTag()} onChange={setAutoTag} />,}]);gpui-ui/src/features/report/register.tsxis a small real example. Controls (Toggle,Choice,Segmented,TextField,Btn,Value) are ingpui-ui/src/settings/controls.tsx. The control must read signals inside its function so it stays reactive. -
A new section: call
registerSection({ id, label, icon, order })first. A section may also use the lower-levelregisterSettingsSectionfromgpui-ui/src/registry.tswith its ownrender(). -
If users will look for it, add its words to
keywords, and mention it on the matching page of the settings guide.
Add a feature
A feature is a folder gpui-ui/src/features/<name>/ with a register.tsx exporting register():
- Create the folder with your UI, a small client for any core routes (for example
client.ts), and pure logic in files with*.test.tsbeside them. - In
register()use the registry ingpui-ui/src/registry.ts:registerItemAction,registerCollectionAction,registerAppAction(the toolbar’s add and tools menus, with an optional global shortcut),registerOverlay(a dialog that owns its open state),registerSidebarSection,registerSettingsSection. - Import it and add it to the list in
gpui-ui/src/features/index.ts.gpui-ui/src/features.tscalls that once after the app mounts. Features that are not in that folder, such as saved searches and reader plugins, register throughgpui-ui/src/searches/register.tsandgpui-ui/src/reader/register.ts. - If it needs data, add the route in
corefirst (HTTP API) and a test there. - Keep features out of each other’s files. The registry exists so they can stay independent.
Add a migration
Follow the steps in Database: a new file in core/src/migrations/, appended to MIGRATIONS in list.ts with the next id, never editing a released migration, with a test in core/test/migrations.test.ts.
Update a translator
Translators come from the zotero/translators repository.
- To try newer translators without changing the repository:
bun core/scripts/update-translators.ts --data <scratch folder>writes<scratch folder>/translators, which the app prefers when the library database is in that folder, or pointZN_TRANSLATORS_DIRat any folder of translator files. - To move the baseline that everyone gets: change the commit in the
PINStable ofcore/scripts/fetch-zotero-vendor.ts, re-run it with--force, run the core tests, and let the script rewritecore/vendor/zotero/README.md(do not edit it by hand). CI caches the vendored folder on the hash of the script, so a new pin refreshes the cache. - Do not edit vendored files. They are unmodified AGPL-3.0 copies; see Translators.
Documentation
User pages are in docs/user-guide/, developer pages in docs/developer-guide/. Use relative links between pages, write commands that work from a fresh checkout, and put facts in code comments where they would otherwise go stale. Do not include real keys, tokens or personal paths in examples; use placeholders such as <repo> and %APPDATA%.