chadtmiller.com/hud
A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts
place.hud.hudkit 0.3.1 Latest 5 packages
0
0
---
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
<script lang="ts">
import '@hud/renderer/theme.css';
import '@hud/shell/shell.css';
</script>
```
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 <version>`, 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<version>`.
```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`).