Thanks for your interest in contributing! Bug reports, feature requests, PRs, and translations are all welcome.
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.
- Node.js 22+
- pnpm 10+
- Chrome or Firefox (for testing)
git clone https://github.com/westpoint-io/mimik.git
cd mimik
pnpm installpnpm dev # Chrome (MV3) with HMR
pnpm dev:firefox # Firefox (MV3) with HMRWXT launches a fresh browser instance with the extension loaded.
pnpm build # Chrome → .output/chrome-mv3/
pnpm build:firefox # Firefox → .output/firefox-mv3/
pnpm zip:all # package both browserspnpm test # run all tests once
pnpm test:watch # watch mode
pnpm test:cov # coverage reportpnpm lint # check
pnpm lint:fix # auto-fix
pnpm format # format onlysrc/
├── core/ # Business logic (no UI dependencies)
│ ├── capture/ # Recording pipeline (events, AI, DOM context)
│ ├── blur/ # Smart blur (regex presets, DOM scanner, panel)
│ ├── export/ # HTML, PDF, Markdown generators
│ ├── guideme/ # Guide replay (finder, overlay, session)
│ └── guides/ # Data layer (types, Dexie DB, CRUD)
├── entrypoints/ # WXT extension entry points
│ ├── background/ # Service worker: state machine + message handlers
│ ├── content.ts # Content script: event capture + rrweb
│ ├── sidepanel/ # Side panel React mount
│ ├── fullview/ # Full-page dashboard mount
│ ├── onboarding/ # First-install wizard
│ └── options/ # Settings page mount
├── locales/ # YAML translation files (en, es, pt-BR, fr)
├── lib/ # Shared utilities (messaging, port, browser API)
├── stores/ # Zustand state stores
└── ui/ # React components
| 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 + HTML/Markdown |
| AI (optional) | Vercel AI SDK (OpenAI, Anthropic) |
| i18n | @wxt-dev/i18n + YAML locales |
| Testing | Vitest + Testing Library |
- 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.
To add a new language:
- Create
src/locales/{lang-code}.yml(e.g.,src/locales/de.yml) - Copy the structure from
src/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)
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)