{"id":20522138,"url":"https://github.com/hossain-khan/android-compose-app-template","last_synced_at":"2026-04-21T04:32:48.509Z","repository":{"id":261984901,"uuid":"885900822","full_name":"hossain-khan/android-compose-app-template","owner":"hossain-khan","description":"An Android App template that is preconfigured with Circuit UDF architecture.","archived":false,"fork":false,"pushed_at":"2026-04-13T20:28:08.000Z","size":974,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-13T22:27:53.842Z","etag":null,"topics":["android-architecture","android-circuit","android-template","circuit","compose","compose-circuit-udf","jetpack-compose","udf"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hossain-khan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-09T17:30:57.000Z","updated_at":"2026-04-13T20:28:14.000Z","dependencies_parsed_at":"2024-12-05T05:19:03.086Z","dependency_job_id":"d9ea1af9-8a8f-4962-865a-4a49e4267a24","html_url":"https://github.com/hossain-khan/android-compose-app-template","commit_stats":null,"previous_names":["hossain-khan/android-compose-app"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/hossain-khan/android-compose-app-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hossain-khan%2Fandroid-compose-app-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hossain-khan%2Fandroid-compose-app-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hossain-khan%2Fandroid-compose-app-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hossain-khan%2Fandroid-compose-app-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hossain-khan","download_url":"https://codeload.github.com/hossain-khan/android-compose-app-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hossain-khan%2Fandroid-compose-app-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32076961,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T02:38:07.213Z","status":"ssl_error","status_checked_at":"2026-04-21T02:38:06.559Z","response_time":128,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android-architecture","android-circuit","android-template","circuit","compose","compose-circuit-udf","jetpack-compose","udf"],"created_at":"2024-11-15T22:34:11.274Z","updated_at":"2026-04-21T04:32:48.502Z","avatar_url":"https://github.com/hossain-khan.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Android - Circuit App Template\nAn Android App template that is preconfigured with ⚡️ Circuit UDF architecture.\n\n\u003e [!CAUTION]\n\u003e Since [`1.0.0`](https://github.com/hossain-khan/android-compose-app-template/releases/tag/1.0.0) release this this template has extended it's feature set\n\u003e and does not adhere to templating realm any more. If you plan to use latest version, you may have to spend extra time deleting features that you don't want.\n\u003e Browse the 🏷️ [1.0](https://github.com/hossain-khan/android-compose-app-template/tree/1.0.0) tagged release to read original instructions.\n\n## What do you get in this template? 📜\n* ✔️ [Circuit](https://github.com/slackhq/circuit) library setup for the app\n* ✔️ [Metro](https://zacsweers.github.io/metro/) Dependency Injection for all Circuit Screens \u0026 Presenter combo\n* ✔️ [OkHttp](https://square.github.io/okhttp/) \u0026 [Retrofit](https://square.github.io/retrofit/) networking with [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization) and sample API implementation\n* ✔️ GitHub Actions for CI and automated release builds\n* ✔️ Automated APK/AAB builds with keystore signing (see [RELEASE.md](RELEASE.md))\n* ✔️ [Google font](https://github.com/hossain-khan/android-compose-app-template/blob/main/app/src/main/java/app/example/ui/theme/Type.kt#L9-L14) for choosing different app font.\n* ✔️ `BuildConfig` turned on with example of reading config from `local.properties` file.\n* ✔️ [Kotlin formatter](https://github.com/jeremymailen/kotlinter-gradle) plugin for code formatting and linting\n* ✔️ [Work Manager](https://developer.android.com/develop/background-work/background-tasks/persistent) for scheduling background tasks\n* ✔️ [Dev Container](.devcontainer) for a ready-to-use Android development environment in VS Code or GitHub Codespaces\n\n\u003e [!WARNING]\n\u003e _This template is only for Android app setup. If you are looking for a multi-platform supported template,_\n\u003e _look at the official [Circuit](https://github.com/slackhq/circuit) example apps included in the project repository._\n\n### Post-process after cloning 🧑‍🏭\n\n1. Checkout the cloned repo\n2. Navigate to repo directory in your terminal\n\nYou have **two options** for customizing this template:\n\n\u003cdetails\u003e\n\u003csummary\u003eOption 1: Automated Customization (Recommended)\u003c/summary\u003e\n\n#### Option 1: Automated Customization (Recommended) 🤖\nRun the setup script to automatically handle most of the configuration:\n\n**Script Usage:**\n```bash\n./setup-project.sh \u003cpackage-name\u003e \u003cAppName\u003e [flags]\n```\n\n**Parameters:**\n- `\u003cpackage-name\u003e` - Your app's package name in reverse domain notation (e.g., `com.mycompany.appname`)\n- `\u003cAppName\u003e` - Your app's class name in **PascalCase** (e.g., `TodoApp`, `NewsApp`, `MyPhotos`)\n  - Used to rename `CircuitApp` → `{AppName}App`\n  - Becomes your main Application class name\n  - Sets app display name in `strings.xml`\n  - Used in git commit messages\n\n**Examples:**\n```bash\n# Basic usage - keeps examples and WorkManager by default\n./setup-project.sh com.mycompany.appname MyAppName\n\n# Remove WorkManager if you don't need background tasks\n./setup-project.sh com.mycompany.appname MyAppName --remove-workmanager\n\n# Remove example screens and data layer for a clean starting point\n./setup-project.sh com.mycompany.appname MyAppName --remove-examples\n\n# Keep the script for debugging (useful during development)\n./setup-project.sh com.mycompany.appname MyAppName --keep-script\n```\n\n**What the script does automatically:**\n- Renames package from `app.example` to your preferred package name\n- Preserves subdirectory structure (`ui/theme/`, `di/`, `circuit/`, `work/`, `data/`)\n- Updates app name and package ID in XML and Gradle files\n- Renames `CircuitApp` to `YourAppNameApp`\n- Keeps WorkManager files by default (use `--remove-workmanager` to exclude)\n- Keeps example screens by default (use `--remove-examples` to exclude)\n- Creates a fresh git repository with descriptive initial commit\n- Removes template-specific files\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eOption 2: Manual Customization 🔧\u003c/summary\u003e\n\n#### Option 2: Manual Customization 🔧\nIf you prefer manual control, complete these tasks:\n\n* [ ] Rename the package from **`app.example`** to your preferred app package name.\n* [ ] Update directory structure based on package name update\n* [ ] Update app name and package id in XML and Gradle\n* [ ] Rename `CircuitApp***` to preferred file names\n* [ ] Remove `Example***` files that were added to showcase example usage of app and Circuit.\n* [ ] Remove WorkManager and Worker example files if you are not using them.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eAdditional Manual Steps (Both Options) 📝\u003c/summary\u003e\n\n#### Additional Manual Steps (Both Options) 📝\nThese still need to be done manually after using the script:\n\n* [ ] Update `.editorconfig` based on your project preference\n* [ ] Update your app theme colors (_use [Theme Builder](https://material-foundation.github.io/material-theme-builder/)_)\n* [ ] Generate your app icon (_use [Icon Kitchen](https://icon.kitchen/)_)\n* [ ] Update/remove repository license\n* [ ] Configure [renovate](https://github.com/apps/renovate) for dependency management or remove [`renovate.json`](https://github.com/hossain-khan/android-compose-app-template/blob/main/renovate.json) file\n* [ ] Choose [Google font](https://github.com/hossain-khan/android-compose-app-template/blob/main/app/src/main/java/app/example/ui/theme/Type.kt#L16-L30) for your app, or remove it.\n* [ ] Verify Android Gradle Plugin (AGP) version compatibility with your development environment in `gradle/libs.versions.toml`\n* [ ] **(Optional)** Set up production keystore for release builds - see [RELEASE.md](RELEASE.md) for automated APK signing\n\n\u003c/details\u003e\n\n\n## Dev Container 🐳\n\nThis template includes a [Dev Container](.devcontainer) configuration for a ready-to-use Android development environment.\n\n\u003cdetails\u003e\n\n### Features\n- **Base Image**: Java 21 (Bookworm)\n- **Android SDK**: Automatically installed via post-create script (API 36, Build Tools 36.0.0)\n- **VS Code Extensions**: Kotlin, Gradle, Java, and GitHub Copilot support\n- **ADB Access**: Configured with `--privileged` mode to allow connecting physical Android devices\n\n### Usage\n\n1. Open the project in VS Code\n2. When prompted, click **\"Reopen in Container\"** (or run `Dev Containers: Reopen in Container` from the Command Palette)\n3. Wait for the container to build and the post-create script to complete\n\nYou can also open this project directly in [GitHub Codespaces](https://github.com/features/codespaces).\n\n### Available Commands\n\n```bash\n# Build the project\n./gradlew build\n\n# Run tests\n./gradlew test\n\n# Format Kotlin code\n./gradlew formatKotlin\n\n# Lint Kotlin code\n./gradlew lintKotlin\n```\n\n\u003c/details\u003e\n\n## Demo 📹\nHere is a demo of the template app containing screens shown in the 📖 [circuit tutorial](https://slackhq.github.io/circuit/tutorial/) documentation.\n\nThe demo showcases the basic Circuit architecture pattern with screen navigation and state management.\n\nhttps://github.com/user-attachments/assets/56d6f28b-5b46-4aac-a30e-80116986589e\n\n\n### Templated Apps\nHere are some apps that has been created using the template.\n\n| 📱 App | Repo URL | \n| ------ | ------- |\n| \u003cimg alt=\"google-play\" src=\"https://github.com/user-attachments/assets/18725aa7-ea0b-4d6d-962a-e0358703041c\" height=\"14\"\u003e Weather Alert | https://github.com/hossain-khan/android-weather-alert |\n| \u003cimg alt=\"google-play\" src=\"https://github.com/user-attachments/assets/18725aa7-ea0b-4d6d-962a-e0358703041c\" height=\"14\"\u003e Remote Notify | https://github.com/hossain-khan/android-remote-notify |\n| \u003cimg alt=\"google-play\" src=\"https://github.com/user-attachments/assets/18725aa7-ea0b-4d6d-962a-e0358703041c\" height=\"14\"\u003e TRMNL Display | https://github.com/usetrmnl/trmnl-android |\n| \u003cimg alt=\"google-play\" src=\"https://github.com/user-attachments/assets/18725aa7-ea0b-4d6d-962a-e0358703041c\" height=\"14\"\u003e TRMNL Buddy | https://github.com/hossain-khan/trmnl-android-buddy | \n| \u003cimg alt=\"google-play\" src=\"https://github.com/user-attachments/assets/18725aa7-ea0b-4d6d-962a-e0358703041c\" height=\"14\"\u003e Math Pup Tutor | https://github.com/hossain-khan/kids-math-tutor | \n\n\n## 📓 Additional References\n\n\u003cdetails\u003e\n    \u003csummary\u003eMetro Usage\u003c/summary\u003e\n\n\n## Metro Dependency Injection 🔧\n\nThis template uses [Metro](https://zacsweers.github.io/metro/latest/) (v0.10.4) - a modern, multiplatform Kotlin dependency injection framework. \n\n\u003e **What is Dependency Injection?** DI is a design pattern that provides objects (dependencies) to a class rather than having the class create them itself. This makes code more testable, maintainable, and modular.\n\nMetro combines the best features of:\n- **Dagger**: Lean, efficient generated code with compile-time validation\n- **kotlin-inject**: Simple, Kotlin-first API design\n- **Anvil**: Powerful aggregation and contribution system\n\n### Key Metro Features Used\n\nThe template demonstrates several Metro patterns:\n\n- **[Dependency Graphs](https://zacsweers.github.io/metro/latest/dependency-graphs/)**: `AppGraph` is the root DI component scoped to the application lifecycle\n- **[Constructor Injection](https://zacsweers.github.io/metro/latest/injection-types/#constructor-injection)**: Activities and other classes use constructor-based DI\n- **[Aggregation](https://zacsweers.github.io/metro/latest/aggregation/)**: `@ContributesTo` automatically contributes bindings to the graph without explicit wiring\n- **[Multibindings](https://zacsweers.github.io/metro/latest/bindings/#multibindings)**: Activity and Worker factories use map multibindings for flexible injection\n- **[Assisted Injection](https://zacsweers.github.io/metro/latest/injection-types/#assisted-injection)**: Workers mix runtime parameters with injected dependencies\n- **[Scopes](https://zacsweers.github.io/metro/latest/scopes/)**: `@SingleIn(AppScope::class)` ensures singleton instances\n\n### Metro 0.10.x Modern Patterns\n\n**Since Metro 0.10.0**, the `contributesAsInject` feature is enabled by default, making `@Inject` implicit on:\n- `@ContributesBinding`\n- `@ContributesIntoMap`\n- `@ContributesIntoSet`\n\nThis means you no longer need to explicitly annotate contributing classes with `@Inject` - it's automatic! ✨\n\n### Metro Implementation Examples\n\nBelow are simplified examples from the template. See the actual implementation files for complete details.\n\n```kotlin\n// AppGraph - Root dependency graph\n@DependencyGraph(scope = AppScope::class)\n@SingleIn(AppScope::class)\ninterface AppGraph {\n    val circuit: Circuit\n    val workManager: WorkManager\n    // ... other graph accessors\n    \n    @DependencyGraph.Factory\n    interface Factory {\n        fun create(@ApplicationContext @Provides context: Context): AppGraph\n    }\n}\n\n// Activity with constructor injection (no @Inject needed!)\n@ActivityKey(MainActivity::class)\n@ContributesIntoMap(AppScope::class, binding = binding\u003cActivity\u003e())\nclass MainActivity(\n    private val circuit: Circuit,\n) : ComponentActivity() {\n    // ... activity implementation\n}\n\n// Worker with assisted injection (requires additional annotations for multibinding)\n@AssistedInject\nclass SampleWorker(\n    context: Context,\n    @Assisted params: WorkerParameters,\n) : CoroutineWorker(context, params) {\n    // ... worker implementation\n    \n    // Note: Requires @WorkerKey and @AssistedFactory annotations\n    // See app/src/main/java/app/example/work/SampleWorker.kt for complete example\n}\n```\n\nFor complete Metro documentation and advanced features, see the [official Metro documentation](https://zacsweers.github.io/metro/latest/).\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhossain-khan%2Fandroid-compose-app-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhossain-khan%2Fandroid-compose-app-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhossain-khan%2Fandroid-compose-app-template/lists"}