What You’ll Need
- Node.js ≥ 18
- Python ≥ 3.10 (only needed to run the test suite)
- A modern browser — Firefox 111+, Chrome 102+, or Safari 16.4+. TrainUs relies on OPFS (Origin Private File System) for its database, which doesn’t exist in older browsers or in private/incognito windows.
Clone and Install
git clone <repo-url>
cd trainUs
npm install
Run the App
npm run dev
This starts the Vite dev server at http://localhost:5173. Open it in your browser — on first launch, TrainUs creates a local database and generates a random user ID for you. There’s nothing else to configure: no .env file, no server, no account.
A Quick Tour of src/
You don’t need to memorize this — just enough to know where to look:
| Folder | What’s in it |
|---|---|
views/ | One Vue component per route (ExerciseListView.vue, SettingsView.vue, …) |
components/ | Smaller, reusable pieces used across views (dialogs, the action bar, …) |
composables/ | Reactive state + logic shared between components (useExercises, useSessionExecution, …) |
db/ | Everything SQLite: the worker, the schema, and one repository per entity in db/repositories/ |
i18n/locales/ | Translation files — en.json, fr.json, da.json |
styles/ | CSS variables (theming) and global layout rules |
utils/ | Small pure helper functions (validation, date formatting, Markdown rendering, …) |
The Reference page covers this in full detail — schema, routes, every composable. Keep it open in a tab once you start working on something real.
Run the Test Suite
TrainUs is tested end-to-end with Playwright, driven from Python. The dev server starts automatically for the duration of the test run — you don’t need npm run dev running separately.
cd tests
python -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/playwright install firefox chromium
cd ..
npm test # Firefox only — the project's primary target
npm run test:parallel # Firefox + Chromium, in parallel
See tests/README.md in the repository for the full setup if anything above doesn’t work out of the box.
Make a Small Change
Before tackling anything real, it’s worth closing the loop once: edit something, see it reload, run the checks.
With
npm run devrunning, opensrc/i18n/locales/en.jsonand change the value of"settings.title"to something else — e.g."Settings (testing)".Save the file. The browser should hot-reload and show your change on the Settings page.
Revert the change, then run the formatter to confirm your editor setup matches the project’s:
npm run format:check
That’s the full inner loop: edit → reload → format check. The How-to Guides page walks through complete, realistic tasks (adding a language, adding a theme, deploying, adding a migration) built on exactly this loop.
Going Further
- How-to Guides — concrete recipes for common contributor tasks.
- Reference — architecture, database schema, routes, and every composable, in detail.
- Understanding the Architecture — the why behind the choices: local-first, the Worker thread, the migration system.