--- title: Building an app on HUD section: HUD order: 9 summary: "HUD's packages for the web, iOS and Android, the registries they come from, and how they're versioned and released." --- An app built on HUD draws what HUD's server resolves with HUD's own renderers, and calls HUD's tools for its data. Grain is one. The renderers and what goes around them come as packages, published from HUD's `main` to HUD's registries on knotless, so an app takes a version of them as it takes any other dependency. | Platform | Package | From | | --- | --- | --- | | Web | `@hud/renderer`, `@hud/shell`, `@hud/shared` | npm, `https://knotless.dev/npm/did:plc:bcgltzqazw5tb6k2g3ttenbj/3n2kdckpvmnlo/` | | iOS | `hud.HUDKit` | Swift package registry, `https://knotless.dev/swift/did:plc:bcgltzqazw5tb6k2g3ttenbj/3n2kdckpvmnlo/` | | Android | `place.hud:hudkit` | Maven, `https://knotless.dev/maven/did:plc:bcgltzqazw5tb6k2g3ttenbj/3n2kdckpvmnlo/` | Each registry belongs to HUD's repository on knotless, named by its owner's DID and the repository's key (`3n2kdckpvmnlo`), which don't change. Reading them needs no login. ## Versions HUD has one version. The server, its crates and every package above share it, so `@hud/shell` 0.2.0, HUDKit 0.2.0 and hudkit 0.2.0 were made from the same commit, and they draw what a 0.2.0 server resolves. `CHANGELOG.md` says what changed in each version for an app built on HUD. An app file names the server versions it runs on in its `hud` ([HUD versions](views.md#hud-versions)), and `hud check` loads the app as that server would ([checking apps](views.md#checking-apps)). Each kit says its version as it calls HUD: HUDKit's `Kit.version`, hudkit's `BuildConfig.HUD_VERSION` (its `hudVersion`) and the web shell's package version, each bumped by knope with the rest. So a build in someone's hands gets trees it can draw, and an app file names the oldest kit its builds still use ([old builds and new views](views.md#old-builds-and-new-views)). A pull that changes what such an app sees (a component, a prop, what a tree draws) adds a change file under `.changeset/`, as `knope document-change` writes one (https://knope.tech). It names the bump (`patch`, `minor` or `major`) in its front matter, then a heading and a line for the app's authors. In 0.x a `major` bumps the minor, and a `minor` or `patch` the patch. A component or prop it adds says the version it arrives in, its `since` in the catalog (`p!("tone", TONE, since "0.3.0")`). ## On the web `@hud/renderer` draws a resolved tree (`Tree`) and the pieces around it, `@hud/shell` draws an app from its app file (its frame, tabs and screens, on a server and hydrated), and `@hud/shared` reads a tool result (`@hud/shared/result`, `@hud/shared/interactions`). Each is Svelte 5 components and modules with their types, built by `svelte-package`, with Svelte as a peer dependency. Point the `@hud` scope at HUD's registry, then install them: ```ini # .npmrc @hud:registry=https://knotless.dev/npm/did:plc:bcgltzqazw5tb6k2g3ttenbj/3n2kdckpvmnlo/ ``` ```sh npm install @hud/renderer @hud/shell @hud/shared ``` In a SvelteKit app, import the stylesheets once, in the root layout, the renderer's first: ```svelte ``` Then draw with `Shell` from `@hud/shell`, and read the page's screen on the server with `@hud/shell/server` (`screenAt`, `frameData`, `lookHead`, `Sessions`). The packages leave relative imports without extensions, as a bundler resolves them, and SvelteKit's Vite bundles any package that exports Svelte, so they need no config of their own. Inside HUD's own `web/`, the packages resolve to their source. Their exports name it under the `@hud/source` condition, which `web/vite.config.ts`, `web/tsconfig.json` and the server tests' builds ask for, so a change shows without a build. `cd web && npm run package` builds each package's `dist`, which is what a release publishes. ## On iOS HUDKit is a Swift package with `Package.swift` in `ios/HUDKit`. The registry has it as `hud.HUDKit`, published as an archive of that directory. Name HUD's registry for the `hud` scope, for your user (Xcode reads that) or for one package: ```sh swift package-registry set --global --scope hud https://knotless.dev/swift/did:plc:bcgltzqazw5tb6k2g3ttenbj/3n2kdckpvmnlo/ ``` Then depend on it in a `Package.swift`: ```swift dependencies: [.package(id: "hud.HUDKit", from: "0.2.0")], targets: [.target(name: "App", dependencies: [.product(name: "HUDKit", package: "hud.HUDKit")])] ``` Xcode resolves it as SwiftPM does, once the registry is set for your user. HUDKit needs iOS 17. The archives aren't signed, so SwiftPM warns that `hud.HUDKit` isn't signed as it fetches it. ## On Android hudkit is the Gradle module `android/hudkit`, published as `place.hud:hudkit`: its release AAR, its sources, a POM and Gradle's module metadata, naming what it depends on (Compose's BOM, OkHttp, kotlinx.serialization and the rest). It brings MapLibre Native's OpenGL ES build in place of the Vulkan one, so an app needs no substitution for it. Add HUD's repository for `place.hud` alone: ```kotlin // settings.gradle.kts dependencyResolutionManagement { repositories { google() mavenCentral() maven("https://knotless.dev/maven/did:plc:bcgltzqazw5tb6k2g3ttenbj/3n2kdckpvmnlo/") { content { includeGroup("place.hud") } } } } ``` ```kotlin // app/build.gradle.kts dependencies { implementation("place.hud:hudkit:0.2.0") } ``` hudkit needs `minSdk` 28 and Compose. `cd android && ./gradlew :hudkit:publishToMavenLocal` puts the version in the tree into `~/.m2`, to try it in an app with `mavenLocal()`. ## Releasing A release starts from the change files on `main`. Ask for `release-pull` at `main` and it opens (or brings up to date) a pull titled `Release `, which `knope release` made: every version in `knope.toml` bumped, the version's `CHANGELOG.md` section, the change files gone. ```sh knotless run rerun knotless://chadtmiller.com/hud --ref refs/heads/main --workflow release-pull ``` Once it lands, ask for `release` at `main`. It builds the web packages, HUDKit's archive and hudkit's AAR, publishes each to its registry as the owner, and tags the commit `v`. ```sh knotless run rerun knotless://chadtmiller.com/hud --ref refs/heads/main --workflow release ``` It skips a package whose version is out already, so a run that failed partway is asked for again to finish. Until knotless.dev serves the Swift and Maven registries, it builds HUDKit and hudkit and says it skipped publishing them. Asked for at another branch, it builds everything and publishes nothing. Both run on ci.knotless.dev with `RELEASE_PASSWORD`, an app password of the owner's, sealed to that runner for `main` alone (`knotless secret set`).