Contributing

Thank you for helping improve StockFill! This guide explains how to set up a local environment, follow the coding conventions, and submit changes.

Ground rules

StockFill is an offline-first PWA. Avoid adding remote API calls or backend dependencies.
Dexie is the source of truth for persisted data. Schema updates must be applied via Dexie migrations to avoid data loss.
Use TypeScript with strict mode and prefer named exports for new modules.
Keep components and hooks small and focused; avoid files exceeding a few hundred lines where possible.
Follow the existing mobile-first UX patterns and preserve accessibility cues.

Node.js 20+ and npm
Optional: Docker for containerized builds and previews
Optional: Playwright browsers for running npm run test:e2e (npx playwright install)

Create small, focused branches for each feature or fix.
Keep PWA assets up to date when changing files in src/pwa/; the build step copies them into public/.
Ensure offline behavior remains intact by exercising flows without network connectivity when possible.

Run these commands before submitting a pull request:

Lint: npm run lint
Unit/component tests: npm test
Coverage (enforced at 80%+ for statements/branches/functions/lines): npm run test:coverage
End-to-end tests (optional, requires browsers): npm run test:e2e

Write clear commit messages that describe the change.
Provide context in pull request descriptions: what changed, why, and how it was tested.
Avoid introducing breaking schema changes without a migration plan.

Include reproduction steps, expected vs. actual behavior, and environment details (browser, OS, device type).
Attach screenshots for UI regressions when possible.