Skip to content
Navvy Navvy

Contributing

Navvy is developed as a monorepo with a WXT browser extension and the standalone websites in website/.

Project structure

Section titled “Project structure”
packages/extension/     Browser extension built with WXT, TypeScript, and React 19
website/landing/        Astro marketing site
website/docs/           Astro Starlight documentation site

The extension is organized around these entrypoints:

  • src/entrypoints/sidepanel/App.tsx for the React chat UI, settings links, and history views.
  • src/entrypoints/background.ts for tab orchestration and Chrome runtime message routing.
  • src/entrypoints/content.ts for DOM detection, page actions, and main-world bridge injection.
  • src/entrypoints/main-world.ts for the optional PAGE_AGENT_EXT page API.

Run the extension in dev mode

Section titled “Run the extension in dev mode”
Terminal window
cd packages/extension
npm install
npm run dev

WXT handles the Manifest V3 build and generated browser output.

Run the websites

Section titled “Run the websites”

Landing site:

Terminal window
cd website/landing
npm install
npm run dev

Docs site:

Terminal window
cd website/docs
npm install
npm run dev

The landing dev server can proxy /docs to the docs server when both are running.

Provider setup for development

Section titled “Provider setup for development”

The current repository does not include a FastAPI backend. Configure the extension with an OpenAI-compatible provider profile using:

  • baseURL
  • model
  • optional apiKey

Local development can use an endpoint such as Ollama’s http://localhost:11434/v1 when the chosen model supports the required tool-calling behavior.

Pull request guidelines

Section titled “Pull request guidelines”
  • Keep changes narrowly scoped.
  • Include tests or reproducible manual verification steps.
  • Make errors visible and actionable.
  • Avoid hiding model failures behind silent retries.
  • Document security-relevant behavior changes.

Code style

Section titled “Code style”
  • Type public interfaces explicitly.
  • Keep action schemas strict.
  • Prefer small tool implementations over broad conditionals.
  • Write comments only where they clarify non-obvious behavior.
  • Keep all code and comments in English.

Security contributions

Section titled “Security contributions”

Security fixes should include the threat model, the attack scenario, and the expected failure mode. For prompt-injection work, test hidden DOM content, misleading labels, and schema-violating model outputs.