Android - Circuit App Template

An Android App template that is preconfigured with ⚡️ Circuit UDF architecture.

Tip

Google also has an official architectural template available for starter apps. https://github.com/android/architecture-templates

What do you get in this template? 📜

• ✔️ Circuit library setup for the app
• ✔️ Metro Dependency Injection for all Circuit Screens & Presenter combo
• ✔️ GitHub Actions for CI
• ✔️ Google font for choosing different app font.
• ✔️ BuildConfig turned on with example of reading config from local.properties file.
• ✔️ Kotlin formatter plugin for code formatting and linting
• ✔️ Work Manager for scheduling background tasks

Warning

This template is only for Android app setup. If you are looking for a multi-platform supported template, look at the official Circuit example apps included in the project repository.

Post-process after cloning 🧑‍🏭

First, download the template:

1. Download the latest template: android-compose-app-template-main.zip
2. Extract the ZIP file to your desired location
3. Navigate to the extracted directory in your terminal

You have two options for customizing this template:

Option 1: Automated Customization (Recommended)

Option 1: Automated Customization (Recommended) 🤖

Run the setup script to automatically handle most of the configuration:

Script Usage:

./setup-project.sh <package-name> <AppName> [flags]

Parameters:

• <package-name> - Your app's package name in reverse domain notation (e.g., com.mycompany.appname)
• <AppName> - Your app's class name in PascalCase (e.g., TodoApp, NewsApp, MyPhotos)
  • Used to rename CircuitApp → {AppName}App
  • Becomes your main Application class name
  • Sets app display name in strings.xml
  • Used in git commit messages

Examples:

# Basic usage - keeps examples and WorkManager by default
./setup-project.sh com.mycompany.appname MyAppName

# Remove WorkManager if you don't need background tasks
./setup-project.sh com.mycompany.appname MyAppName --remove-workmanager

# Keep the script for debugging (useful during development)
./setup-project.sh com.mycompany.appname MyAppName --keep-script

# Flags can be positioned flexibly - all of these work the same:
./setup-project.sh com.mycompany.appname MyAppName --remove-workmanager

What the script does automatically:

• Renames package from app.example to your preferred package name
• Preserves subdirectory structure (ui/theme/, di/, circuit/, work/, data/)
• Updates app name and package ID in XML and Gradle files
• Renames CircuitApp to YourAppNameApp
• Keeps WorkManager files by default (use --remove-workmanager to exclude)
• Creates a fresh git repository with descriptive initial commit
• Removes template-specific files

Option 2: Manual Customization 🔧

Option 2: Manual Customization 🔧

If you prefer manual control, complete these tasks:

• Rename the package from app.example to your preferred app package name.
• Update directory structure based on package name update
• Update app name and package id in XML and Gradle
• Rename CircuitApp*** to preferred file names
• Remove Example*** files that were added to showcase example usage of app and Circuit.
• Remove WorkManager and Worker example files if you are not using them.

Additional Manual Steps (Both Options) 📝

Additional Manual Steps (Both Options) 📝

These still need to be done manually after using the script:

• Update .editorconfig based on your project preference
• Update your app theme colors (use Theme Builder)
• Generate your app icon (use Icon Kitchen)
• Update/remove repository license
• Configure renovate for dependency management or remove renovate.json file
• Choose Google font for your app, or remove it.
• Verify Android Gradle Plugin (AGP) version compatibility with your development environment in gradle/libs.versions.toml

Demo 📹

Here is a demo of the template app containing screens shown in the 📖 circuit tutorial documentation.

The demo showcases the basic Circuit architecture pattern with screen navigation and state management.

Circuit-Template-App-DEMO.mp4