You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
137 lines
3.2 KiB
137 lines
3.2 KiB
# App Boilerplate
|
|
|
|
A modular, offline-first Flutter boilerplate for apps that store, sync, and share media and metadata across centralized (Immich, Firebase) and decentralized (Nostr) systems.
|
|
|
|
## Phase 0 - Project Setup
|
|
|
|
- Flutter project skeleton with config loader
|
|
- Testing framework setup
|
|
- CI workflow
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Install dependencies
|
|
flutter pub get
|
|
|
|
# Run tests (important: separate from running the app!)
|
|
flutter test
|
|
|
|
# Or run on Android (wait for emulator to fully boot first)
|
|
flutter run
|
|
|
|
# Run with specific environment
|
|
flutter run --dart-define=ENV=prod
|
|
```
|
|
|
|
**Note:** `flutter run` launches the app but does not run tests. Always run `flutter test` separately to verify tests pass.
|
|
|
|
## Configuration
|
|
|
|
### Config Files Location
|
|
|
|
Configuration is defined in code at:
|
|
- `lib/config/app_config.dart` - Configuration model
|
|
- `lib/config/config_loader.dart` - Environment loader (where to tweak values)
|
|
|
|
### How to Modify Config
|
|
|
|
Edit `lib/config/config_loader.dart` to change environment values:
|
|
|
|
```dart
|
|
// Current dev config (lines 36-40)
|
|
case 'dev':
|
|
return const AppConfig(
|
|
apiBaseUrl: 'https://api-dev.example.com', // ← Change this
|
|
enableLogging: true, // ← Change this
|
|
);
|
|
|
|
// Current prod config (lines 41-45)
|
|
case 'prod':
|
|
return const AppConfig(
|
|
apiBaseUrl: 'https://api.example.com', // ← Change this
|
|
enableLogging: false, // ← Change this
|
|
);
|
|
```
|
|
|
|
### Environment Variables
|
|
|
|
Currently, the app uses compile-time environment variables via `--dart-define`:
|
|
|
|
```bash
|
|
# Set environment at runtime
|
|
flutter run --dart-define=ENV=prod
|
|
```
|
|
|
|
**Future:** `.env` file support can be added in later phases. When implemented, `.env` files would go in the project root and be loaded at runtime.
|
|
|
|
### Available Environments
|
|
|
|
- `dev` - Development (default): Logging enabled, dev API URL
|
|
- `prod` - Production: Logging disabled, production API URL
|
|
|
|
## Running the App
|
|
|
|
### Android Emulator
|
|
|
|
**Important:** Wait for emulator to fully boot (30-60 seconds on cold boot).
|
|
|
|
1. Start emulator from Android Studio AVD Manager
|
|
2. Wait for boot animation to complete and home screen appears
|
|
3. Run: `flutter run`
|
|
|
|
### iOS Simulator (macOS)
|
|
|
|
```bash
|
|
open -a Simulator
|
|
flutter run
|
|
```
|
|
|
|
## Running Tests
|
|
|
|
```bash
|
|
# Run all tests
|
|
flutter test
|
|
|
|
# Run with coverage
|
|
flutter test --coverage
|
|
```
|
|
|
|
**Important:** Tests must be run separately - `flutter run` does not execute tests.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
lib/
|
|
├── config/
|
|
│ ├── app_config.dart # Config model
|
|
│ └── config_loader.dart # Environment loader (edit here!)
|
|
└── main.dart
|
|
|
|
test/
|
|
└── config/
|
|
└── config_loader_test.dart
|
|
|
|
.github/workflows/
|
|
└── flutter-ci.yml
|
|
```
|
|
|
|
## CI/CD
|
|
|
|
GitHub Actions workflow (`.github/workflows/flutter-ci.yml`) runs on push/PR to `main` or `master` branches:
|
|
|
|
**Workflow steps:**
|
|
1. **Checkout code** - `actions/checkout@v4`
|
|
2. **Setup Flutter** - Flutter 3.24.0 (stable channel)
|
|
3. **Install dependencies** - `flutter pub get`
|
|
4. **Run tests** - `flutter test`
|
|
5. **Report results** - Success/failure messages
|
|
|
|
**Commands executed:**
|
|
```bash
|
|
flutter pub get
|
|
flutter test
|
|
```
|
|
|
|
The workflow runs on Ubuntu latest and reports test results in the GitHub Actions UI.
|