82 lines
3.9 KiB
Markdown
82 lines
3.9 KiB
Markdown
---
|
|
title: 'Getting Started'
|
|
description: 'Set up your dev environment, run TrainUs locally, and make your first change.'
|
|
slug: 'getting-started'
|
|
weight: 1
|
|
date: 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
|
|
|
|
```bash
|
|
git clone <repo-url>
|
|
cd trainUs
|
|
npm install
|
|
```
|
|
|
|
## Run the App
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
1. With `npm run dev` running, open `src/i18n/locales/en.json` and change the value of `"settings.title"` to something else — e.g. `"Settings (testing)"`.
|
|
2. Save the file. The browser should hot-reload and show your change on the Settings page.
|
|
3. Revert the change, then run the formatter to confirm your editor setup matches the project's:
|
|
|
|
```bash
|
|
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.
|