- Kotlin 58.3%
- Python 22.1%
- Java 17.7%
- Shell 1.9%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .forgejo | ||
| .source-size | ||
| Config | ||
| config/detekt | ||
| designsystem | ||
| gradle | ||
| icons | ||
| observability | ||
| Scripts | ||
| .editorconfig | ||
| .gitignore | ||
| AGENTS.md | ||
| build.gradle.kts | ||
| gradle.properties | ||
| gradlew | ||
| gradlew.bat | ||
| README.md | ||
| settings.gradle.kts | ||
fjord-android-kit
Shared Android libraries for Fjord apps: the Fjord Android app and Fjord Grid. One repository, one
version tag, three library modules. The Apple counterpart is fjord-apple-kit; the version numbers
are independent.
| Module | Namespace | What it is |
|---|---|---|
:designsystem |
sh.fjord.kit.designsystem |
Theme (colors, typography with its three fonts, contrast and status bar handling), layout policy, large-text and reduce-motion helpers, FjordIcon, the dropdown menu, pull to refresh and the preview surface. |
:observability |
sh.fjord.kit.observability |
Crash reporting that names nothing from an app: the consent-gated CrashReporter, the Sentry sink, the scrubbers, the install id, the build channel, launch tracing and the analytics policy and region helpers. |
:icons |
sh.fjord.icons |
The icon set (drawables, FjordIcons, FjordSymbol), generated from fjord-icons for the union of the apps' usage lists. |
None of them depends on a Forgejo client, a Fjord Account client or Push, so an app that is not a Forgejo client can use them.
Packages still read com.rasterstate.fjord.ui.* and com.rasterstate.fjord.observability: the code
moved here unchanged from fjord-android so no import in the app had to move. A later release renames
them; the version notes will say so.
Use
Composite build first. Add this repository as a checkout pinned to a tag, then in the app's
settings.gradle.kts:
includeBuild("fjord-android-kit")
and depend on the modules by group and name:
implementation("sh.fjord.kit:designsystem")
implementation("sh.fjord.kit:observability")
minSdk 26, Kotlin 2.4, Compose BOM as in gradle/libs.versions.toml. Keep the host's Android Gradle
Plugin, Kotlin and Compose BOM in step with it.
Things a host app provides
- Observability configuration. Install an
ObservabilityConfigurationfirst thing at launch (Application.attachBaseContext), before anything reads the engine: application id, version name and code, whether the build is debuggable, the Sentry DSN, the operated URLs and the rest. Until then the engine seesObservabilityConfiguration.Unconfigured, which fails closed: no DSN, no key, every host redacted. - Consent storage and failure facts. The host implements
AnalyticsSettings(where the crash reporting consent lives) andFailureFacts(which of its exceptions are an HTTP refusal, came from the person's own server or are the person's state) and builds aCrashReporter(settings, sink, facts). - Sentry.
:observabilitydepends onsentry-androidat the version pinned ingradle/libs.versions.toml. Pin the same version in the app so it links one SDK. The Sentry Gradle plugin (ProGuard mapping upload) stays on the app. The library manifest setsio.sentry.auto-init=false, so the SDK starts only throughSentryCrashSink.enableafter consent; a host that sets the same key itself overrides it. - Design system strings and artwork. The loaders, the splash scene and the list status views are not in the kit yet: they use the app's strings and drawables and move when the strings do.
Icons
Config/icons-usage/<app>.json lists the icon keys one app uses. The kit packages the union of all the
lists, so an app can use an icon another app added without a second vendoring step.
Scripts/update-icons.sh ../fjord-icons # a clean fjord-icons checkout at Config/fjord-icons-revision
CI runs Scripts/check_icons_usage.py: every listed icon is carried, nothing unlisted is, and the
manifest, FjordIcons.java and the five drawable densities agree. A list edited without regenerating
fails on the pull request.
Build
android.builder.sdkDownload=false is set, so a build never downloads an SDK component behind your back:
a missing one fails by name. A checkout needs JDK 17 and an Android SDK with platforms;android-37.0
(revision 2), build-tools;36.0.0 and platform-tools 37.0.1. CI installs exactly these, verified by hash,
with .forgejo/scripts/install-jdk.sh and .forgejo/scripts/install-android-sdk.sh; run the same two
scripts (they write to $HOME and $GITHUB_ENV/$GITHUB_PATH) or install the same components with
sdkmanager.
Checks
./gradlew spotlessCheck detekt assembleDebug assembleRelease testDebugUnitTest lintDebug, then the icon
check above, and the source-size check (150-line target, 200-line limit per file; see AGENTS.md):
cd .source-size/tool && python3 -B -m source_size -C ../.. check --base origin/main --worktree. CI runs both on the Linux Android runners (JDK 17 and the Android SDK come from the Forgejo
package registry, the way fjord-android installs them).
Versions
Tags are semantic versions of this repository. A host app pins an exact tag. The first tag is 0.1.0.