Backpack Battles

An Ionic Capacitor mobile game for Android built with React, TypeScript, and game engines like Phaser and Konva.

🎮 About

Backpack Battles is a mobile game that combines the power of React with native mobile capabilities through Ionic and Capacitor. The game features 2D rendering with Phaser and Konva, native device integrations, and a modern React-based architecture.

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Node.js 22.20.0 (recommended via mise)
Java OpenJDK 21 (for Android development)
Android Studio (for Android development and emulator)
Android SDK (installed via Android Studio)
Git

Environment Setup (Recommended)

This project uses mise for environment management. Install mise and run:

# Install mise if you haven't already
curl https://mise.run | sh

# Install project dependencies and setup environment
mise install

Manual Environment Setup

If not using mise, ensure you have:

# Node.js 22.20.0
# Java OpenJDK 21
# Gradle 8.11

# Set environment variables
export ANDROID_HOME=$HOME/Android/Sdk
export ANDROID_SDK_ROOT=$HOME/Android/Sdk
export JAVA_HOME=/path/to/your/java-21
export PATH=$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$ANDROID_HOME/tools/bin:$PATH

Installation

Clone the repository

git clone <repository-url>
cd backpack-battles

Install dependencies
```
npm install
```
Install Ionic CLI globally
```
npm install -g @ionic/cli@latest
```

Initial setup (with mise)

mise run setup

Or manually:

npm run build
npx cap add android
npx cap sync android
npx cap doctor

Android Development Setup

Install Android Studio from developer.android.com
Setup Android SDK through Android Studio:
- Open Android Studio
- Go to Tools > SDK Manager
- Install the latest Android SDK Platform and SDK Build Tools
Create Android Virtual Device (AVD):
- Open Android Studio
- Go to Tools > AVD Manager
- Create a new virtual device (recommended: Pixel 6 with API 34)

🛠️ Development

Web Development

Start the development server for browser testing:

# Using npm
npm run dev

# Using mise (alternative)
mise run dev

The app will be available at http://localhost:5173

Android Development

Build and Sync

# Using mise (recommended)
mise run android-build

# Manual
npm run build
npx cap sync android

Run on Device/Emulator

# Using mise (recommended)
mise run android-run

# Manual
npm run build
npx cap sync android
npx cap run android

Open in Android Studio

# Using mise (recommended)
mise run android-open

# Manual
npm run build
npx cap sync android
npx cap open android

📋 Available Scripts

Core Development

npm run dev - Start Vite development server
npm run build - Build TypeScript and create production bundle
npm run preview - Preview production build locally

Testing & Quality

npm run test.unit - Run unit tests with Vitest
npm run test.e2e - Run end-to-end tests with Cypress
npm run lint - Run ESLint for code quality

Mise Tasks (if using mise)

mise run dev - Start Ionic development server
mise run android-build - Build and sync to Android
mise run android-run - Build, sync, and run on Android
mise run android-open - Open in Android Studio
mise run android-reset - Clean and reset Android platform

🏗️ Tech Stack

Framework: React 19.1.0 with TypeScript 5.9.2
Mobile: Ionic React 8.7.5 + Capacitor 7.4.3
Game Engine: Phaser 3.90.0
2D Rendering: Konva 10.0.2 + React-Konva 19.0.10
State Management: Zustand 5.0.8
Audio: Howler.js 2.2.4
Storage: LocalForage 1.10.0
Build Tool: Vite 7.1.7
Testing: Vitest 3.2.4 (unit) + Cypress 13.17.0 (e2e)
Linting: ESLint 9.36.0

📱 Native Features

The app includes various Capacitor plugins for native functionality:

AdMob integration
Haptic feedback
Push notifications
Device information
File system access
Screen orientation control
And more...

📦 Dependency Management

Important: This project uses fixed/pinned versions for all dependencies to ensure consistent builds and prevent automatic updates.

All package versions in package.json are exact versions (no ^ or ~ prefixes)
Versions are synchronized with package-lock.json for reproducible builds
Manual updates only - dependencies will not auto-update during npm install
Dependabot automation creates PRs for review, but requires manual approval

🤖 Dependabot Automation

This project uses GitHub Dependabot with a sophisticated three-tier update system that balances automation with safety.

⏰ Update Schedule

Update Type	Frequency	Time	Description
🟢 Patch	Daily	06:00 UTC	Bug fixes, security patches
🟡 Minor	Daily	06:00 UTC	New features, backwards compatible
🔴 Major	Daily	06:00 UTC	Breaking changes, requires migration

Note: All update types are checked daily in a single Dependabot run.

📋 PR Structure

🟢 Patch Updates (Low Risk)

Single bundled PR with ALL patch updates
Quick review and approval process
Example: deps: Update all-patch-updates group
Labels: dependencies, dependabot, needs-review

🟡 Minor Updates (Medium Risk)

Grouped by functional area for logical testing
Up to 5 group PRs at once
Groups:
- minor-ionic-react - Framework components
- minor-game-stack - Phaser, Konva, Howler
- minor-dev-toolchain - Vite, TypeScript, build tools
- minor-testing-tools - Cypress, ESLint, testing libraries
- minor-utilities - Zustand, storage, misc packages
Labels: dependencies, dependabot, needs-review

🔴 Major Updates (High Risk)

Individual PRs for each breaking change
No grouping - each major update gets separate PR
Requires changelog review and migration planning
Labels: dependencies, dependabot, needs-review

🏷️ Label System

Dependabot PRs are automatically tagged with GitHub's standard labels:

Standard Labels

dependencies - All dependency updates
dependabot - Created by Dependabot
needs-review - Requires manual review and approval

Update Types (GitHub auto-detects)

Patch updates: Generally safe bug fixes
Minor updates: New features, should be backwards compatible
Major updates: Breaking changes, requires careful review

Risk Assessment

🟢 Patch updates - Quick review, usually safe to merge
🟡 Minor updates - Test recommended, grouped logically
🔴 Major updates - Individual review required, check changelogs

🔄 Daily Pattern

Every day 06:00 UTC: Check for all updates (🟢 Patches + 🟡 Minors + 🔴 Majors)

What you'll see:

1 patch PR - If any patch updates available
Up to 5 minor PRs - Grouped by functional area
Individual major PRs - One per breaking change (up to 15 total PRs max)

📝 Manual Dependency Updates

When updating dependencies manually:

# Check for outdated packages
npm outdated

# Update specific package (example)
npm install @ionic/react@8.8.0

# Update package.json to exact version after testing
# Then commit both package.json and package-lock.json
git add package.json package-lock.json
git commit -m "deps: Update @ionic/react to 8.8.0"

🛡️ Security Updates

Security patches are included in daily patch updates and should be prioritized:

Look for security labels from Dependabot
Review security advisories in PR descriptions
Test and merge security patches quickly

📈 Managing Dependabot PRs

Daily Workflow:

Morning: Review any new Dependabot PRs from overnight
Patch PRs: Quick review and merge (usually safe)
Minor PRs: Test by functional group if concerned
Major PRs: Careful individual review, check changelogs

PR Management:

Max 15 concurrent PRs - merge or close to allow new updates
Patch updates: Bundle of all patches in one PR
Minor updates: Logical groupings for easier testing
Major updates: Individual attention for breaking changes

Best Practices:

Merge patch updates quickly to reduce PR backlog
Test minor updates in development environment
Research major updates thoroughly before merging
Monitor PR count - Dependabot stops creating new PRs when limit reached

🔍 Code Quality & Testing

This project implements PHPStan-style static analysis for TypeScript, ensuring code quality equivalent to PHPStan Level 6-7.

Static Analysis Features

❌ No any types allowed - Full type safety enforced
✅ Unused import/variable detection - Dead code elimination
✅ React hook dependency validation - Memory leak prevention
✅ Security rules - No eval(), dynamic code execution blocked
✅ Mobile-specific optimizations - Performance and security rules

Git Hooks & Quality Gates

Every git push automatically runs:

TypeScript type checking - Full codebase analysis
ESLint static analysis - PHPStan-equivalent validation
Unit tests - Functionality verification
Quality warnings - Console.log detection, TODO scanning

Push will be REJECTED if:

❌ TypeScript compilation fails
❌ ESLint errors found
❌ Unit tests fail

# Run quality checks manually
npm run type-check  # TypeScript analysis
npm run lint        # ESLint static analysis
npm run pre-push    # Full pre-push validation

🚀 CI/CD Pipeline

Our streamlined GitHub Actions pipeline ensures code quality with a 5-job sequential workflow:

📋 Unified PR Validation Pipeline

Triggers: All PRs to any branch (except Dependabot PRs) • Duration: ~20-30 minutes

Job 1: Static Analysis (~5 minutes)

🔍 Dependency verification - Pinned versions validation
🔧 TypeScript type checking - Full codebase analysis
📝 ESLint static analysis - PHPStan-equivalent rules

Job 2: CodeQL Security Analysis (~10-15 minutes) - Main PRs Only

🛡️ JavaScript/TypeScript security scanning - Vulnerability detection
🚨 SQL injection, XSS, auth bypass detection - Advanced security analysis
📊 Results uploaded to Security tab - Integrated reporting

Job 3: Testing & Building (~10 minutes) - Needs Jobs 1 & 2

🧪 Unit tests - Vitest test suite
🏗️ Build verification - Production build success
🎭 E2E tests - Cypress browser testing
📦 Build artifacts - Upload for next jobs

Job 4: Bundle Analysis & Validation (~5 minutes) - Needs Job 3

📊 Bundle size analysis - Performance monitoring
🩺 Capacitor doctor - Mobile platform validation

Job 5: Android APK Build (~15-20 minutes) - Main PRs Only

📱 Only runs on PRs to main - Feature branches skip
🔨 Debug APK generation - Ready for device testing
📤 APK artifacts - 30-day retention with download

🛡️ Security & Release Management

Integrated Security Scanning

Integration: Built into PR validation as Job 2
Triggers: PRs to main only (after static analysis passes)
Features: JavaScript/TypeScript vulnerability detection, automated reporting
Results: Repository → Security → Code scanning alerts

Manual Release Management

Strategy: Manual releases as needed
APK Source: Built via PR validation workflow (Job 5)
Process: Manual GitHub release creation with tested APKs

Sequential Job Flow

graph TD
    A[Job 1: Static Analysis<br/>Dependencies + TypeScript + ESLint] --> B[Job 2: CodeQL Security<br/>Security Scanning - Main PRs Only]
    A --> C[Job 3: Testing & Building<br/>Unit Tests + E2E + Build + Artifacts]
    B --> C
    C --> D[Job 4: Bundle Analysis<br/>Bundle Size + Capacitor Doctor]
    D --> E[Job 5: Android APK Build<br/>Main PRs Only]

    style A fill:#e1f5fe
    style B fill:#ffebee
    style C fill:#f3e5f5
    style D fill:#fff3e0
    style E fill:#e8f5e8

Quality Gates & Benefits

✅ Progressive validation - Each job must pass before the next starts ✅ Integrated security - CodeQL scanning built into PR workflow ✅ Efficient resource usage - Security & APK builds only for main PRs ✅ Artifact sharing - Build outputs passed between jobs ✅ Comprehensive reporting - Detailed summary of all job results

🔧 Troubleshooting

Common Issues

1. Git push rejected by hooks

# Check what's failing
npm run pre-push

# Fix common issues
npm run lint:fix        # Auto-fix ESLint errors
npm run type-check      # See TypeScript errors
npm run test.unit       # Run tests to see failures

2. Android build fails

Ensure Java 21 is installed and JAVA_HOME is set correctly
Run npx cap doctor to check Capacitor configuration
Try mise run android-reset to clean and rebuild

3. CI/CD workflow failures

Check workflow logs in GitHub Actions tab
Download artifact logs for debugging
Verify dependencies are pinned (no ^ or ~ prefixes)

4. Static analysis errors

# Common ESLint fixes
npm run lint:fix                    # Auto-fix imports, formatting
# Remove console.log from production code
# Add proper TypeScript types instead of 'any'
# Fix React hook dependencies

5. Dependency issues

If you encounter version conflicts, check that all versions in package.json match package-lock.json
Delete node_modules and run npm install if needed
Remember: versions are pinned, so npm update won't change anything

Getting Help

If you encounter issues:

Check the comprehensive documentation in this repository
Review Ionic documentation
Review Capacitor documentation
Run npx cap doctor for environment diagnostics

🤝 Development Workflow

Create feature branch from main
Make changes to React/TypeScript code in src/
Test locally with npm run dev
Quality checks run automatically on git push
Create PR - triggers full CI/CD validation
Review and merge - Android APK built for main PRs
Tag releases - triggers production builds

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

Development Guide - Local development workflow, quality standards
CI/CD Workflows - GitHub Actions, automation, troubleshooting
Dependency Management - Dependabot configuration, update strategy
Security Practices - Security scanning, best practices
Release Management - Version tagging, APK creation

📄 License

This project is private and not licensed for public use.

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.github		.github
.husky		.husky
.vscode		.vscode
cypress		cypress
docs		docs
public		public
src		src
.browserslistrc		.browserslistrc
.gitignore		.gitignore
.mise.toml		.mise.toml
CLAUDE.md		CLAUDE.md
README.md		README.md
capacitor.config.ts		capacitor.config.ts
cypress.config.ts		cypress.config.ts
eslint.config.js		eslint.config.js
index.html		index.html
ionic.config.json		ionic.config.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

millerphp/backpack-battles

Folders and files

Latest commit

History

Repository files navigation