fegger
3c6df95a86
Add TypeScript project references, update ESLint configs to support ESM modules, and introduce brand semantic color tokens across the web app. Add comprehensive documentation for architecture, API reference, development setup, and user guide.
102 lines
4.1 KiB
Markdown
102 lines
4.1 KiB
Markdown
# Development Guide
|
|
|
|
This guide covers setting up the development environment, running the applications, and maintaining code quality.
|
|
|
|
## 🛠 Prerequisites
|
|
|
|
- **Node.js:** Version 20.x or higher.
|
|
- **npm:** Version 9.x or higher.
|
|
|
|
## 📥 Installation
|
|
|
|
1. **Clone the repository:**
|
|
```bash
|
|
git clone <repository-url>
|
|
cd TimeToLeave
|
|
```
|
|
|
|
2. **Install dependencies:**
|
|
```bash
|
|
npm install
|
|
```
|
|
*This installs dependencies for the root workspace as well as all apps and packages.*
|
|
|
|
3. **Environment Variables:**
|
|
- Web App: Copy `apps/web/.env.example` to `apps/web/.env` and configure your HAFAS/Geocoding API keys.
|
|
- Mobile App: Copy `apps/mobile/.env.example` to `apps/mobile/.env` and set the backend API URL.
|
|
|
|
## ▶️ Running the Applications
|
|
|
|
| Script | Command | Description |
|
|
| :--- | :--- | :--- |
|
|
| `dev` | `npm run dev` | Starts the Next.js development server (Web) on `http://localhost:3000`. |
|
|
| `dev:mobile` | `npm run dev:mobile` | Starts the Expo development server (Mobile) and opens the Expo Go simulator. |
|
|
| `build` | `npm run build` | Builds the production bundle for the Web application. |
|
|
|
|
## 🧪 Testing & Quality Assurance
|
|
|
|
The project enforces strict typing and linting across all workspaces.
|
|
|
|
| Script | Command | Description |
|
|
| :--- | :--- | :--- |
|
|
| `test` | `npm run test` | Runs **Vitest** for the Web app (using jsdom & React Testing Library) and **Jest** for the Mobile app (using jest-expo). |
|
|
| `lint` | `npm run lint` | Runs **ESLint 9** across the entire monorepo. |
|
|
| `typecheck` | `npm run typecheck` | Runs **TypeScript 5** type checking across all workspaces. |
|
|
|
|
### Testing Specific Packages
|
|
If you want to run tests for a specific workspace:
|
|
```bash
|
|
cd apps/web && npm test
|
|
cd apps/mobile && npm test
|
|
cd packages/core && npm run typecheck
|
|
```
|
|
|
|
## 🐳 Docker Support (Web App)
|
|
|
|
The web application includes a `Dockerfile` and `docker-compose.yml` for containerized development or deployment.
|
|
|
|
```bash
|
|
cd apps/web
|
|
docker-compose up --build
|
|
```
|
|
|
|
## 📁 Web App Routing (Next.js 16)
|
|
|
|
The web app uses the Next.js App Router. Key routes include:
|
|
|
|
| Route | Description |
|
|
| :--- | :--- |
|
|
| `/` | **Dashboard:** Lists upcoming events and their real-time leave status. |
|
|
| `/calendar` | **Calendar Sync:** Interface to import `.ics` files or paste calendar URLs. |
|
|
| `/add-event` | **Manual Entry:** Add a new event manually without a calendar source. |
|
|
| `/event/[id]` | **Event Details:** Deep dive into a specific event, showing journey options, delays, and local routing. |
|
|
|
|
### Backend API Routes
|
|
The web app acts as a proxy for external APIs. These are located in `apps/web/src/app/api/`:
|
|
|
|
| Endpoint | Method | Description |
|
|
| :--- | :--- | :--- |
|
|
| `/api/health` | `GET` | Health check for the backend proxy. |
|
|
| `/api/calendar` | `GET` | Fetch and parse remote `.ics` files. |
|
|
| `/api/calendar/parse` | `POST` | Parse raw `.ics` content. |
|
|
| `/api/hafas` | `POST` | Generic HAFAS protocol endpoint (TripSearch, LocMatch). |
|
|
| `/api/geocode` | `GET` | Forward geocoding (Nominatim). |
|
|
| `/api/geocode/reverse`| `GET` | Reverse geocoding. |
|
|
| `/api/bike-route` | `GET` | Bicycle routing between coordinates. |
|
|
| `/api/walk-route` | `GET` | Walking routing between coordinates. |
|
|
| `/api/wienerlinien/stops`| `GET` | Find nearby WienerLinien stops. |
|
|
|
|
## 📱 Mobile App Structure
|
|
|
|
The mobile app is organized into the following directories:
|
|
|
|
- `src/screens/`: UI screens (`EventListScreen`, `EventDetailScreen`, `AddEventScreen`, `CalendarImportScreen`, `SettingsScreen`).
|
|
- `src/navigation/`: React Navigation configuration (`AppNavigator.tsx`).
|
|
- `src/services/`: API integration and data fetching services.
|
|
- `src/store/`: Local state management and AsyncStorage integration.
|
|
|
|
## ⚠️ Development Notes
|
|
|
|
1. **Next.js 16 Breaking Changes:** The web app runs on Next.js 16.2+, which introduces breaking changes in routing and API conventions. Always check `node_modules/next/dist/docs/` if you encounter unexpected behavior.
|
|
2. **HAFAS Timezones:** Never parse HAFAS times using standard `Date` methods. Use `@timetoleave/core` utilities (`parseHafasTime`, `hafasDateTime`) to ensure accurate CET/CEST and DST handling.
|