---
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.