3.9 KiB
| title | description | slug | weight | date |
|---|---|---|---|---|
| Getting Started | Set up your dev environment, run TrainUs locally, and make your first change. | getting-started | 1 | 2026-06-16 |
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]({{< relref "technical.en.md" >}}) 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]({{< relref "how-to-guides.en.md" >}}) 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]({{< relref "how-to-guides.en.md" >}}) — concrete recipes for common contributor tasks.
- [Reference]({{< relref "technical.en.md" >}}) — architecture, database schema, routes, and every composable, in detail.
- [Understanding the Architecture]({{< relref "understanding-the-architecture.en.md" >}}) — the why behind the choices: local-first, the Worker thread, the migration system.