Bookmark ScoutContributing and development
Set up the Bookmark Scout monorepo, build the extension from source, run the tests, and open a pull request.
Contributions are welcome: bug reports, fixes, translations, and docs. The full guidelines are in CONTRIBUTING.md; this page covers the commands you need.
The repository
A Bun and Nx monorepo with three apps and two packages:
| Path | What |
|---|---|
apps/extension | The browser extension: WXT, React, TypeScript, Zustand, and shadcn/ui on Base UI |
apps/website | The marketing site: Next.js, localized with next-intl |
apps/docs | This site: Next.js, Fumadocs, and MDX in content/docs |
packages/config | Project and site values read from config/project.toml and config/web.toml |
packages/mcp-bridge | bookmark-scout-mcp, the MCP server and native messaging host for local AI agents |
Set up
You need Bun and Chrome, Edge, or Firefox. Fork the repository on GitHub, clone your fork, and in its folder run:
bun install
bun run devbun run dev starts the extension in Chrome with live reload. Use bun run dev:edge or bun run dev:firefox for the other browsers.
Build from source
bun run buildThis builds all three browser targets into apps/extension/dist/:
| Browser | Folder |
|---|---|
| Chrome | apps/extension/dist/chrome-mv3 |
| Edge | apps/extension/dist/edge-mv3 |
| Firefox | apps/extension/dist/firefox-mv2 |
Load the folder for your browser as an unpacked extension, the same way as a downloaded release in Install: Load unpacked in Chrome and Edge, or Load Temporary Add-on with the folder's manifest.json in Firefox. To build one browser, run bunx nx run extension:build:chrome, extension:build:edge, or extension:build:firefox.
Test
bun run testThis builds the Chrome target, installs Playwright's Chromium, and runs the unit tests and the Chromium end-to-end tests headless. Network tools and AI tools run against local servers and mocked providers; tests titled [mocked provider contract] check Bookmark Scout's side of the provider contract, not live provider compatibility.
| Change | Run |
|---|---|
| Extension source | bunx nx run extension:lint |
| Services, hooks, and other logic | bun run test:unit |
| Popup, settings, manager, tools, import and export | bun run test:e2e |
| Edge behavior | bunx nx run extension:test:e2e:edge |
| Firefox behavior | bunx nx run extension:test:e2e:firefox (a smoke suite) |
Local AI agents or packages/mcp-bridge | bun test packages/mcp-bridge and bunx nx run extension:test:e2e:bridge (Linux and macOS) |
| Speed on a large library | bunx nx run extension:test:perf, before and after the change |
| AI features against a real provider | bunx nx run extension:test:live, with the BS_LIVE_AI_* variables set; it is skipped without them |
| Manifest, provider, or browser integration | bunx nx run extension:build:chrome plus each affected browser target |
| Website | bunx nx run website:build |
| Docs | bunx nx run docs:build, then bunx nx run docs:verify |
| Changes across apps | bun run lint and bun run build:all |
CI runs lint, the three extension builds, the unit and Chromium end-to-end tests, the Edge suite, and the Firefox smoke suite as required checks on every pull request, and the bridge tests when the extension or the bridge changes. The performance suite runs daily and the live AI suite only on demand. A passing build is not test coverage: say which tests you ran.
Work on the docs
bun run dev:docsPages are MDX files in apps/docs/content/docs, ordered by the meta.json files next to them. Links to the website, the repository, releases, and contact addresses come from config through small components such as <Contact role="support" /> and <ReleaseLink />, so pages never hard-code them. bunx nx run docs:verify checks the static export after a build.
Translations
User-facing extension text lives in apps/extension/public/_locales/<locale>/messages.json, and website text in apps/website/messages/<locale>.json. Change every language together; the unit tests and the website build check fail when a key is missing. To add a language, follow "Localization" in apps/extension/AGENTS.md.
Pull requests
- Branch from
mainand keep each pull request to one change. - Write commits as Conventional Commits with a Gitmoji prefix, for example
🐛 fix(popup): keep focus after deleting a folder. - Update the docs when a change affects what users see, browser support, privacy, or settings. Project status lists what is implemented, partial, and planned.
Report security problems privately to security@bookmark-scout.com, not in a public issue. Bookmark Scout is licensed under AGPL-3.0.
Last updated on