Environment setup

Development Environment Setup

This guide covers the complete setup of the development environment for Remind Tools, including all tools, configurations, and best practices.

Quick Start

Automated Setup (Recommended)

# Clone the repository (if not already done)
git clone https://github.com/design4pro/remind_tools.git
cd remind_tools

# Run the automated setup script
./scripts/dev_setup.sh

# Install Git hooks for code quality
./scripts/install_hooks.sh

Manual Setup

If you prefer to set up manually or encounter issues with the automated script:

# 1. Bootstrap the workspace
melos bootstrap

# 2. Install Git hooks
git config core.hooksPath .githooks
chmod +x .githooks/*

# 3. Set up environment
cp .env.example .env
# Edit .env with your actual API keys

# 4. Generate code (if needed)
melos run generate

# 5. Verify setup
make doctor

Environment Configuration

Environment Files

The project uses multiple environment files for different deployment targets:

• .env - Your local development environment (not committed)
• .env.example - Template with placeholder values (committed)
• .env.development - Development environment settings (committed)
• .env.staging - Staging environment settings (committed)
• .env.production - Production environment settings (committed)

Environment Variables

Variable	Description	Required
SUPABASE_URL	Supabase project URL	Yes
SUPABASE_ANON_KEY	Supabase anonymous key	Yes
SUPABASE_SERVICE_KEY	Supabase service role key	Yes
MAPBOX_ACCESS_TOKEN	MapBox access token for maps	Yes
MAPBOX_SECRET_TOKEN	MapBox secret token	No
GEMINI_API_KEY	Google Gemini AI API key	Yes
ENVIRONMENT	Current environment (development/staging/production)	Yes
DEBUG_MODE	Enable debug features	Yes
ENABLE_LOGGING	Enable application logging	Yes

Switching Environments

Use the Makefile commands to quickly switch between environments:

# Switch to development
make env-dev

# Switch to staging  
make env-staging

# Switch to production (be careful!)
make env-prod

# Check current environment
make env-status

VSCode Configuration

The project includes comprehensive VSCode configuration for optimal Flutter development.

Workspace Settings

The .vscode/settings.json file includes:

• Flutter/Dart Configuration: Hot reload, debugging, analysis
• Code Formatting: Auto-format on save, organize imports
• File Management: Hide generated files, nest related files
• Performance: Optimized analysis server settings
• Terminal: Proper PATH configuration for Dart tools

Recommended Extensions

Install these extensions for the best development experience:

{
  "recommendations": [
    "dart-code.dart-code",
    "dart-code.flutter",
    "felix-angelov.bloc",
    "robert-brunhage.flutter-riverpod-snippets",
    "eamodio.gitlens",
    "usernamehw.errorlens",
    "supabase.supabase"
  ]
}

VSCode will automatically suggest these extensions when you open the project.

Debug Configurations

Pre-configured launch configurations for:

• Both Apps: Debug, Profile, Release modes
• Multi-Platform: Web, macOS, iOS, Android
• Testing: Unit tests, Integration tests
• Environment-Specific: Development, Staging, Production

Use Cmd+Shift+D (macOS) or Ctrl+Shift+D (Windows/Linux) to access debug configurations.

Code Generation

Build Configuration

The build.yaml file configures code generation for:

• Freezed: Immutable data classes with copyWith, equality
• JSON Serializable: JSON serialization/deserialization
• Auto Route: Type-safe navigation
• Riverpod: State management providers

Running Code Generation

# Generate code once
melos run generate

# Watch and auto-generate on file changes
melos run generate:watch

# Clean generated files
make clean-generated

Generated File Patterns

Generated files follow these patterns:

• *.g.dart - JSON serializable generated files
• *.freezed.dart - Freezed generated files
• *.gr.dart - Auto route generated files
• *.config.dart - Configuration files

These files are hidden in VSCode but visible in the file system.

Development Scripts

Available Scripts

Use make help to see all available commands, including:

Development

make dev-trips        # Run Trips app
make dev-money        # Run Money app  
make dev-trips-web    # Run Trips app on web
make dev-money-macos  # Run Money app on macOS

Code Quality

make analyze          # Static analysis
make format-fix       # Format code
make lint            # Full linting
make pre-commit      # Pre-commit checks

Testing

make test            # All tests
make test-unit       # Unit tests only
make coverage        # Coverage report

Building

make build-android   # Android APK
make build-ios       # iOS app
make build-web       # Web build
make build-all       # All platforms

Git Hooks

Pre-commit hooks automatically run:

1. Code Formatting: Auto-formats staged Dart files
2. Static Analysis: Runs melos run analyze
3. Security Checks: Prevents committing real secrets
4. Unit Tests: Runs unit tests if available
5. Code Generation: Checks for generated file updates

To bypass hooks temporarily:

git commit --no-verify

Debugging and Logging

Debug Configuration

The project includes comprehensive debug configuration:

// Check if in debug mode
if (DebugConfig.isDebugMode) {
  // Debug-only code
}

// Environment-aware logging
if (DebugConfig.enableLogging) {
  logger.info('Debug message');
}

Logging System

Use the built-in logging system:

import 'package:core/core.dart';

// Use global loggers
Loggers.app.info('Application started');
Loggers.network.debug('API request sent');
Loggers.ui.warning('User interaction warning');

// Or create custom logger
final logger = AppLogger.withTag('MyFeature');
logger.error('Something went wrong', error, stackTrace);

// Use extension method
class MyClass {
  void myMethod() {
    logger.info('Method called');
  }
}

Debug Features

Available debug features:

• Network Inspector: Log all HTTP requests/responses
• Performance Profiling: Measure execution times
• Memory Leak Detection: Track memory usage
• Flutter Inspector: Widget tree debugging
• Layout Debugging: Visual debugging aids

Platform-Specific Setup

macOS Development

# Install Xcode from App Store
# Install Android Studio
# Verify setup
flutter doctor

# Enable desktop development
flutter config --enable-macos-desktop

Web Development

# Enable web development
flutter config --enable-web

# Install Chrome for debugging
# Web builds use CanvasKit renderer by default

Mobile Development

# iOS (macOS only)
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept

# Android
# Set ANDROID_HOME environment variable
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools

Troubleshooting

Common Issues

”Melos not found"

dart pub global activate melos
export PATH="$PATH":"$HOME/.pub-cache/bin"

"Flutter doctor issues"

flutter doctor
# Follow the suggestions to fix issues

"Build failures"

# Clean and rebuild
make clean
make bootstrap
melos run generate

"Git hooks not working"

# Reinstall hooks
./scripts/install_hooks.sh

"VSCode extensions not working”

# Reload VSCode window
Cmd+Shift+P -> "Developer: Reload Window"

Getting Help

1. Check Documentation: Review /docs directory
2. Run Diagnostics: Use make doctor and flutter doctor
3. Clean Setup: Try make reset for a fresh start
4. Team Support: Ask in team channels with error details

Next Steps

After setup, you can:

1. Start Development: Use make dev-trips or make dev-money
2. Explore Code: Check packages/ for shared code
3. Run Tests: Use make test to verify everything works
4. Read Architecture: Review /docs/architecture/
5. Check Issues: Look at GitHub Issues for current tasks

Continuous Integration

The setup works seamlessly with CI/CD:

• GitHub Actions: Uses same melos commands
• Codemagic: Pre-configured build scripts
• Quality Gates: Automated testing and analysis
• Multi-Platform: Builds for all supported platforms

This ensures consistency between local development and production builds.