Technical Manual sections
Reference āŗ Technical Manual āŗ Build and release
While you work on Kitten, run the installer (./install) and use the kitten command to run what it installed. In your working copy, the installer builds Kitten from source (see How it works), so the kitten command runs your latest changes.
The build script creates the distribution in dist/. (The installer runs it for a development install.) It:
Deletes and recreates dist/, and runs update-version.js, which writes dist/node-version and dist/version.json. version.json contains:
date: when the build ran.versionStamp: the same moment in UTC, as a number (e.g.,20261103101500).gitHash: the first six characters of the hash of the latest commit.apiVersion: the major version in package.json.nodeVersion: the version of the Node.js runtime that runs the build (kitten-node).distributionHost: the value ofKITTEN_DISTRIBUTION_HOST, or kittens.small-web.org if it isnāt set.
Bundles the three entry points with esbuild: src/entry/main.ts as kitten-bundle.js, src/entry/update-guard.ts as update-guard.js, and src/entry/loader.js as loader-bundle.js. esbuild itself stays external, as the loader needs esbuildās binary for the platform at run time. The build writes a package.json into the distribution that pins esbuildās version, and the installer installs it.
Installs the dependencies of the internal web app and copies it into dist/web/.
Bundles src/lib/crypto.ts and src/lib/keyStore.ts for the browser, and copies, minifies, and compresses Kittenās images and the client-side libraries from lib/ and node_modules/ into dist/web/š±/.
Copies these into dist/:
the launcher (build-templates/kitten)
the Kitten Process Manager (build-templates/kitten-process-manager.js)
the installer
the runtime checksums (build-templates/runtime-checksums)
the templates of
kitten init(src/cli/commands/init/)kitten-day.sixel
Regenerates CONTRIBUTORS.md in the repository with contributors.js.
src/lib/Version.ts reads version.json at run time and calculates the versionās exactVersion, which the installer uses as the name of the versionās folder in versions/ (see step 3 of How it works).
You can also run the build script on its own and run the result with dist/kitten [path to serve]. Only do this if you have a specific reason to. During everyday development, run the installer.
package runs the installer (which builds and installs the current source) and archives dist/ as packages/kitten-<exact version>.tar.xz. (On macOS, it needs GNU tar, as
gtar.)deploy runs the
packagescript, signs the package with sign-package.js, and checks that the signature verifies againstPUBLIC_KEYS. Then it uploads the package, its signature, and the installer to the distribution server (kittens.small-web.org), with the upload token in theAuthorizationheader.
The signing key and the upload token are in small-web.org/kittens/ in your XDG configuration home (~/.config/ by default): signing-key.pem and secret-token.txt. If you have deployment rights for Kitten, the distribution serverās settings page (_https://kittens.small-web.org/settings/_, which requires sign-in) shows the upload token and lets you reset it.
To release to the staging distribution server (staging.kittens.small-web.org) instead, run ./deploy --staging. The deploy script then exports that host as the KITTEN_DISTRIBUTION_HOST environment variable, so the build writes it into version.json. It also uploads an installer that downloads from that host, and reads the upload token from staging.kittens.small-web.org.secret-token.txt. (The deploy script only takes the host from its arguments, never from the environment, and it prints the host before it runs the package script.) Set LOCAL=true to upload to a distribution server on localhost, with the development token in the deploy script.
To create a signing key pair, run kitten-node generate-signing-key.js <name> (generate-signing-key.js). It writes <name>.pem and <name>.pub.pem to the same folder, refuses to overwrite either, and prints the public key. (sign-package.js uses signing-key.pem.)
The KittenPackage.stage() method only accepts packages signed with a key in the PUBLIC_KEYS of the Kitten that runs it (src/lib/packageSignature.ts). This covers automatic updates, the kitten update command, and the kitten deploy command. To move to a new signing key, add its public key to PUBLIC_KEYS and release that version, signed with the old key, before you sign with the new one.
Note that the installer does not check signatures. It downloads the package from the distribution server over HTTPS.
For each release, make a checklist from this one. Take the steps for every release, add the sections below that apply, and then add anything the release itself needs.
For every release, in this order:
Reinstall Kitten from the release branch. In your working copy, switch to the release branch, check that the tree is clean and that no test suite is running, and run
./install. Then check thatkitten --versionincludes the first six characters of the hash of the branchās latest commit, and run the start-up benchmark (see Testing).The build uses the files in your working copy but takes
gitHashfrom the latest commit (see Building), so a clean tree ensures that the hash matches what you install. (Installing also restarts the Kitten servers that are running in development, including those of a test suite.)Update and test our own apps (e.g., Catalyst and the Kitten site) against this build. Run each app with the installed Kitten and go through its main flows (sign-in, forms, uploads, and live pages). Watch the terminal for errors, warnings, and HTML validation failures. Commit your changes on the branch that the appās server tracks (see Updates), but donāt push them until you have published the release in step 5.
This is because a server installs a new head of its tracked branch with the newest Kitten release for the API version that the head declares. A head that you push before you publish runs on the previous release.
Check the documentation against the change log. Check that this manual and the reference cover every change in the unreleased section of CHANGELOG.md.
Set the release date in the change log. Replace the unreleased heading (e.g.,
## 2026-10-?? [unreleased - breaking]) with the release date, in the form that released entries use (e.g.,## 2026-11-03). Commit, and push to the release branch.The update history in the Settings app links the Kitten version of each confirmed update to CHANGELOG.md at the commit of that versionās build. So the commit you build from must have the release date in the change log, with the section for the release as the first one.
Publish the release with
./deploy(see Releasing). Then check thathttps://kittens.small-web.org/latest/<API version>/responds with the new release, i.e., that itscompatible.gitHashis the first six characters of the hash of the release branchās latest commit.Merge the release branch into main (
git switch main,git merge --ff-only <release branch>, andgit push), only after you publish.This is because Catalyst installs Kitten on new servers with the installer on the default branch (_https://codeberg.org/kitten/app/raw/install_), and that installer downloads the newest package from the distribution server. If you merge first, new servers run the new installer on the previous releaseās package, and the installer refuses a package that doesnāt have what it checks for (see step 2 of How it works).
Tell app authors what changed: the breaking changes in the change log, and anything they must change in their apps (e.g.,
engines.kitten). Tell them to runkitten checkbefore they set theengines.kittenfield.Pick up the follow-ups that you noted during the release.
When the API version changes:
Add a
kitten checkcheck for each breaking change, withapiVersionset to the new API version, in src/lib/check/checks/, list it in src/lib/check/registry.ts, give it before/ and after/ fixtures in tests/fixtures/check/, and mention its ID in the change log entry (see Check).Set
KITTEN_TYPES_MAJOR_VERSIONin src/lib/kittenTypesVersion.ts to the major version of@small-web/kitten-typesthat contains the new API versionās types.Port our own apps to the new API before you test them in step 2. Run
kitten checkon each one first. The breaking changes are in the unreleased section of the change log.Set the
engines.kittenfield in each appās package.json to the new API version (e.g.,"engines": { "kitten": "2" }), and update its@small-web/kitten-typesdependency to the version with this releaseās types (see Types).A server moves Kitten and the app to a new API version together, and only when the head of its tracked branch declares that version. An app without an
engines.kittenfield stays on the API version of the Kitten it runs on.After you publish, push each appās commit to the branch that its server tracks. The server moves on its next check, or when you run
kitten updateon it (see Update for its exit codes).If the change log reports that earlier releases donāt update themselves to this one, move each of our servers by hand, one at a time. Check that lingering is on for the account that runs Kitten (
loginctl show-user <account>reportsLinger=yes), so the service runs after you log out (see Deploy). Then run the installer on the server (curl -sL https://kittens.small-web.org/install | bash), which hands over to the newkitten updatecommand and exits with its exit code (see step 4 of How it works). Finally, check the live app and the newest entry in its update history.
When the update code changes:
Run the automatic updates rehearsal on the release build before you publish, with the scenarios that Updates lists for the files you changed. Run
npm run rehearsalto run the reset and all fifteen scenarios, or pass it the numbers of the scenarios to run after the reset (e.g.,npm run rehearsal -- 1 2 14 6 7 12). Its README.md lists what it needs and the order to run the scenarios in.Each scenario ends with
PASSorFAIL, and stops at the first check that fails. (Therehearsaltask stops at the first scenario that fails.) Donāt publish until every scenario you run passes.
The rehearsal changes real machines and a real repository. On the rehearsal server, it replaces Kitten, its update records, and the systemd unit, deploys the test app, and deletes the test appās earlier deployments and their data. One scenario reboots that server. It force-pushes and deletes main and release in the test repository. On the staging distribution server, the reset deletes all distributions and uploads, and the scenarios upload builds.
When the distribution server changes:
- Deploy kittens.small-web.org before you publish in step 5, so the new server accepts the releaseās upload. Then check that
https://kittens.small-web.org/latest/<API version>/still responds with the previous release.
Kittenās types are in src/types/:
globals.d.ts declares the global
kittenobject.types.d.ts declares the request, response, and other types.
fragments.d.ts declares the modules of fragment files (e.g., *.fragment.html).
client.d.ts declares the globals of a Kitten page in the browser.
index.ts re-exports the types for explicit annotations.
The npm run typecheck script checks the server program and the client program separately (tsconfig.server.json and tsconfig.client.json), as each has its own kitten global. The npm run sync-types script (sync-types.js) regenerates the @small-web/kitten-types package in a types checkout beside the Kitten repository: it emits the declarations of src/types/index.ts with tsconfig.declaration.json, and copies the ambient declaration files.
Source code: