Skip to content

feat(init): create a new Android app with clerk init --starter - #593

Draft
swolfand wants to merge 3 commits into
claude/android-native-setup-v2-bc524ffrom
claude/android-starter
Draft

swolfand wants to merge 3 commits into
claude/android-native-setup-v2-bc524ffrom
claude/android-starter

Conversation

@swolfand

@swolfand swolfand commented Oct 28, 2026 •

Copy link
Copy Markdown

Summary

Stacked on #588: this targets its branch and should be retargeted to main once #588 merges. clerk init now creates a new Android app in an empty folder, the way it already creates iOS and macOS apps. Before this, init stopped there with framework_undetected and the new-project picker had no Android option.

What the starter does

  • Adds "Android (Jetpack Compose)" to the picker. Agents use clerk init --starter --framework android with --name and --android-package (default com.example.<name>). A missing answer is reported as input-required under --json.
  • Writes a project like Android Studio's Empty Activity template: AGP 9.2.1, Kotlin 2.3.21, a Compose BOM, minSdk 24, the Gradle 9.4.1 wrapper, and an initial Git commit.
  • Runs feat(init): set up Android apps natively in clerk init and clerk doctor #588's Android setup on it with the ui artifact. With --prebuilt-auth-ui, or yes at the prompt, MainActivity shows AuthView until sign-in, then UserButton and the user's email.
  • Reports the project folder and a continuation command in the JSON, so an agent can resume setup if it stops partway.

Decisions

  • The wrapper files, including the 45 KB jar, ship inside the CLI. Running gradle wrapper needs a Gradle install most Android developers don't have, and downloading the jar at init would add a network and trust step.
  • The initial commit comes before setup, so Git can restore every edit and no backups are needed.
  • No accountless mode, as with the Apple starters.

Validation

  • Format, lint, typecheck, and unit tests (5,639) pass.
  • From an empty folder against a real Clerk application: one clerk init --starter --framework android … --prebuilt-auth-ui --json run, an all-green clerk doctor, a clean assembleDebug, and on an emulator a test user signed up, saw the signed-in screen, and signed out.
  • The interactive prompts were checked against a local API stub only.

clerk init works in an empty folder for Android as it does for iOS and
macOS: "Android (Jetpack Compose)" joins the picker everywhere, and
--starter --framework android takes --name and --android-package (default
com.example.<lowercased name>); missing answers are StarterInputRequired,
reported as input-required with --json, and no accountless mode applies.

The starter is shaped like Android Studio's Empty Activity template: a
version catalog pinning AGP 9.2.1, Kotlin 2.3.21 through the Compose compiler
plugin alias (AGP 9's built-in Kotlin would be 2.2.10, which the SDK can't be
consumed by), a Compose BOM, an app module with minSdk 24, the manifest,
MainActivity, the theme, a vector launcher icon, .gitignore, an initial Git
commit, and the Gradle 9.4.1 wrapper. The wrapper's scripts and jar are
embedded in the CLI (Bun file imports) and copied in, with the distribution's
checksum pinned in gradle-wrapper.properties, so the project builds with
./gradlew without Gradle on PATH.

The existing Android setup then runs on the new app with no confirmation and
the UI artifact by default. --prebuilt-auth-ui (or a yes to the prompt, on by
default for a new starter) replaces the unchanged MainActivity with the
prebuilt sign-in: progress while Clerk.isInitialized is false, AuthView until
the auth flow completes, then UserButton and the signed-in email. Every JSON
status after the app is written carries the starter and its continuation, and
a setup error becomes setup-interrupted. StarterInputRequired, the starter
summary, and setupInterrupted move to native/ so both engines share them.
@changeset-bot

changeset-bot Bot commented Oct 28, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 017731c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
clerk Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@coderabbitai

coderabbitai Bot commented Oct 28, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Comment @coderabbitai help to get the list of available commands.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant