π¬ A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots π
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
- Fork the repo and create a branch:
git checkout -b feat/your-feature - Make your changes and add tests where applicable
- Run the full check locally before pushing:
pnpm lint && pnpm test && pnpm build && pnpm build:firefox - Use Conventional Commits for commit messages:
feat:new featurefix:bug fixdocs:documentationtest:tests onlychore:tooling/deps
- 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:
- Create
packages/locales/{lang-code}.yml(e.g.,packages/locales/de.yml) - Copy the structure from
packages/locales/en.yml - Translate all values, keeping the keys identical
- Keep substitution placeholders (
$1,$2) in the same positions - 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 Firefoxabout:debuggingβ Inspect)