CONTRIBUTING.md

Contributing

Thank you for your interest in improving Languages Learner.

Prerequisites

• Node.js 20 (see .nvmrc)
• pnpm 10.6.2 — enable Corepack (corepack enable) so the version from the root package.json is used

Setup for development in this repo

pnpm install

To run the web app and the API together, copy .env.example to .env, fill in the Supabase values, and:

pnpm dev          # http://localhost:5173, API on http://localhost:3001
pnpm dev:logs     # follow the backend container's output
pnpm dev:build    # rebuild the backend image after a dependency change
pnpm dev:down     # stop the backend container

pnpm dev starts the backend in Docker (docker-compose.dev.yml) and then runs apps/web natively in the foreground. Stopping it (Ctrl+C) leaves the backend running; pnpm dev:down stops that too.

Why the web app is not containerised. A container reads bind-mounted sources across the host boundary, which costs milliseconds per file rather than microseconds — Vite pays that thousands of times per render, so dev startup and HMR become slow enough to hurt. Containers also receive inotify events only for files stored in the Linux filesystem, so a bind-mounted host directory forces the watcher into polling, adding constant stat() traffic over the same slow boundary. The backend reads files rarely enough that neither cost is noticeable, so it stays in Docker where its runtime is pinned. (On a Linux host both costs disappear; see Docker's WSL 2 best practices for the underlying rules.)

Each service also runs on its own — pnpm --filter app-web dev and pnpm --filter app-backend start:dev.

The public tree does not ship database migrations or a guaranteed-local backend. Use your own Supabase project (or mocks) when your change requires API access.

Checks before a pull request

From the repository root:

pnpm lint
pnpm typecheck
pnpm test:unit

Run package-level scripts (lint, typecheck, tests) when your change touches a specific app or package — see each folder’s README.md and package.json scripts.

Pull requests

• Pull request titles are validated with semantic / conventional format (see .github/workflows/check-pr-title.yml). Use a title such as feat: …, fix: …, or chore: ….
• Keep changes focused and match existing code style and tooling (ESLint, Prettier, Stylelint).

Questions

Open a GitHub issue for bugs or feature discussions. Update the issue link if the repository is under a different owner or name.