mimik/CONTRIBUTING.md

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 → .output/chrome-mv3/
pnpm build:firefox         # Firefox → .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

Project Layout

src/
├── 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

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 + 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.

Adding a Translation

To add a new language:

1. Create src/locales/{lang-code}.yml (e.g., src/locales/de.yml)
2. Copy the structure from src/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)