Contributing to Mimik

Thanks for your interest in contributing! Bug reports, feature requests, PRs, and translations are all welcome.

Licensing

By submitting a pull request or any contribution to this repository, you agree that your contribution will be licensed under the MIT License.

You represent that you have the right to submit the contribution and that it does not infringe any third-party rights.

Development Setup

Prerequisites

• Node.js 22+
• pnpm 10+
• Chrome or Firefox (for testing)

Install

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

Run in development

pnpm dev                   # Chrome (MV3) with HMR
pnpm dev:firefox           # Firefox (MV3) with HMR

WXT launches a fresh browser instance with the extension loaded.

Build

pnpm build                 # Chrome → apps/extension/.output/chrome-mv3/
pnpm build:firefox         # Firefox → apps/extension/.output/firefox-mv3/
pnpm zip:all               # package both browsers

Test

pnpm test                  # run all tests once
pnpm test:watch            # watch mode
pnpm test:cov              # coverage report

Lint & format

pnpm lint                  # check
pnpm lint:fix              # auto-fix
pnpm format                # format only

Code style

Biome handles formatting and linting. Run pnpm lint:fix and it sorts out indentation, quotes, semicolons and import order for you.

One rule Biome cannot check: do not write comments. Name things so the code explains itself. The exceptions are pragmas and directives the toolchain reads, such as @ts-expect-error or biome-ignore. When a piece of logic looks like it needs a comment to be understood, it usually wants a clearer name or a smaller function instead.

Project Layout

apps/extension/           # The browser extension (WXT): entrypoints, capture, blur, guideme, lib, ui
apps/desktop/             # The Electron desktop app: main, preload, renderer
packages/core/            # Logic both apps share: capture, guides, export, screenshot, blur
packages/ui/              # React components both apps share
packages/locales/         # YAML translation files
packages/capture-native/  # Rust addon for the desktop: accessibility lookup and input hook
scripts/                  # Repository checks run by pnpm lint

Tech Stack

| Layer | Technology | |-------|-----------| | Extension framework | WXT (Manifest V3) | | Language | TypeScript | | UI | React 19 + Tailwind CSS v4 | | Components | shadcn/ui | | State (capture) | XState | | State (UI) | Zustand | | Storage | Dexie.js (IndexedDB) | | Messaging | webext-core | | Session recording | rrweb | | Export | jsPDF, docx, mediabunny, gifenc, fflate + HTML/Markdown | | AI (optional) | Vercel AI SDK (OpenAI, Anthropic) | | i18n | @wxt-dev/i18n + YAML locales | | Testing | Vitest + Testing Library |

Pull Request Guidelines

1. Fork the repo and create a branch: git checkout -b feat/your-feature
2. Make your changes and add tests where applicable
3. Run the full check locally before pushing:

   pnpm lint && pnpm test && pnpm build && pnpm build:firefox
   

4. Use Conventional Commits for commit messages:
   • feat: new feature
   • fix: bug fix
   • docs: documentation
   • test: tests only
   • chore: tooling/deps
5. Open a PR with a clear description of what and why

CI (pr-test.yml) will run lint, tests, and both browser builds on every PR.

Using AI Tools

AI-assisted contributions are welcome here.

Name the models you used on the "AI model(s) used" line at the top of the pull request template, or write "None". Saying so costs you nothing. Passing off output you have not read is what gets a PR closed.

That line is the only place AI use is disclosed. Commits are authored by you: do not let a tool set itself as the commit author or add Co-Authored-By, Assisted-by or session-link trailers. If your tool adds them by default, turn that off in its settings.

You are responsible for every line you submit. If a reviewer asks why something is there, "the model wrote it" is not an answer. Be ready to debug it without going back to the tool.

Write the pull request description yourself. Generated summaries run long and restate the diff, which reviewers can already read. Two sentences on what changed and why beats ten paragraphs. Same for issue reports and review comments.

Reproduce a bug before you file it. Issues written by pointing a tool at the codebase, with no real reproduction, get closed unread.

Leave good first issue alone. Those exist for people learning the codebase by hand.

Do not run automated AI reviews on pull requests in this repo. Your own fork is fine.

Repeat submissions of unread AI output will get you blocked.

Adding a Translation

To add a new language:

1. Create packages/locales/{lang-code}.yml (e.g., packages/locales/de.yml)
2. Copy the structure from packages/locales/en.yml
3. Translate all values, keeping the keys identical
4. Keep substitution placeholders ($1, $2) in the same positions
5. Build and test: pnpm build:firefox (WXT generates types for new locale keys automatically)

Reporting Bugs

Open an issue with:

• What you expected to happen
• What actually happened
• Steps to reproduce
• Browser + version (Chrome / Firefox)
• Screenshots if relevant
• Any errors from the extension console (chrome://extensions → Mimik → "service worker" → Console, or Firefox about:debugging → Inspect)