Files
llama.cpp/ui/lib/ui
Aleksander Grygier 97069ff6c4 ui: run Llama Chat with npx @ggml-org/llama-chat (#32524)
* ui: run Llama Chat with npx @ggml-org/llama-chat

Makes @ggml-org/llama-chat publishable: drops private, adds bin,
files, exports, repository and a prepack build. Its CLI serves the
prebuilt dist on localhost (3000 by default) and forwards every other
request to a llama-server (--server, default http://127.0.0.1:8080),
with the headers llama-server sends for the UI. A thin unscoped
llama-chat package in alias/ forwards to it, so npx llama-chat works.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: llama-chat revalidates service-worker.js and asks for a build before packing

SvelteKit 3 adds service-worker.js next to sw.js, and llama-server
revalidates it, so the CLI does too. The folder's .npmrc sets
ignore-scripts, so prepack never ran: it goes, and the publishing steps
build dist explicitly and check the packed file list.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: llama-chat keeps llama-server's DNS rebinding and cross-origin guards

The CLI called llama-server with its own Host and dropped every Origin,
so a rebound host name or another page got past the checks llama-server
makes when --cors-origins is not *. It now drops only its own page's
Origin, passes other Origins and Sec-Fetch-Site through, and, when it
listens on loopback, answers only to localhost and loopback addresses.
`start` on Windows gets its empty title verbatim.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: llama-chat build writes the app to a folder for any static server

`npx @ggml-org/llama-chat build [--out <dir>] [--force]` copies the
prebuilt app, without source maps, to ./llama-chat or the given folder,
so a plain file server can host it next to the CLI serving it. It
refuses a folder that is not empty unless forced, and the serving flags
and build flags refuse each other's command. The README shows serving
the folder with http-server forwarding the API to llama-server.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: publish Llama Chat to npm from CI when its version is bumped

ui-chat-publish.yml publishes @ggml-org/llama-chat and its llama-chat
alias the way ui-lib-publish.yml publishes @ggml-org/llama-ui: the
version is set by hand, and a commit that reaches master with a version
npm does not have builds dist, checks the packed files and publishes both
with trusted publishing. PRs that change the packages get a dry run.
npm-version-check.mjs takes the package folder, so both workflows share
it. ui/README.md says how releases work, and Chat's AGENTS.md says not
to bump versions unless asked to release.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: call the app Llama Chat in its README

The README's title and a few lines still called the app llama-ui or
Llama UI, the name of the library it is built on. They now say Llama
Chat, and the intro points to Llama UI in ui/lib/ui.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: llama-chat connects to llama-server's default port, 9931

The CLI's --server default and its examples used 8080, which is not
where llama-server listens. They now use 9931, its default port, so
npx llama-chat reaches a llama-server started without --port.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: a shorter Llama Chat README that matches the code

The README grew to nearly 900 lines, and its tables of components,
hooks, stores and services had drifted from the code. It now keeps what
a reader needs: running it with npx and self-hosting, a short feature
list, development commands, the architecture (the line between Llama UI
and the app, a table of the layers and where they live, a flowchart and
one sequence diagram for sending a message), a few patterns worth
knowing, cross-origin isolation, how the build is embedded in
llama-server, the project tree and publishing. The folders now carry the
detail the tables used to. ASCII replaces the unicode arrows.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: llama-chat serves only static files, without the API proxy

The CLI forwarded every request it had no file for to llama-server, from
loopback. With --host 0.0.0.0 that let any LAN client reach a llama-server
started on 127.0.0.1 as a local request, tools included, which llama-server
on its own refuses without an API key. The browser now talks to each
llama-server directly, so llama-server's own rules apply. --server is gone,
and anything that is not a file in dist is a 404, or a 405 for other methods.

Assisted-by: Claude (Opus 5.5 Medium)
2026-11-18 12:58:16 +01:00
..

@ggml-org/llama-ui

Llama UI, the design system of Llama Chat and the Llama apps, as a package: its tokens, fonts, surfaces and components, for Llama Chat (ui/apps/chat) and llama.pages (llama.app). It lives in llama.cpp at ui/lib/ui, beside the apps built on it in ui/apps.

Use

/* app.css */
@import 'tailwindcss';
@import 'tw-animate-css';
@import '@ggml-org/llama-brand/css/colors.css';
@import '@ggml-org/llama-ui/theme.css';
<script lang="ts">
	import { Badge, Button } from '@ggml-org/llama-ui';
</script>

<Button variant="secondary">View on Hugging Face</Button>
<Badge variant="success">Downloaded</Badge>
  • theme.css: everything: fonts, tokens, surfaces, the Tailwind theme and base styles. It needs Tailwind 4, tw-animate-css (both peer dependencies) and @ggml-org/llama-brand's css/colors.css imported before it.
  • tokens.css: the three tiers of tokens only, also after @ggml-org/llama-brand's css/colors.css. fonts.css: Llama Sans and Llama Mono. surfaces.css: the matte surface utilities.
  • Dark mode is the dark class on <html>; the Matte light surfaces are the theme-matte class.

What's in it

  • Foundations: the primitive, semantic and component tokens, the type roles (text-body, text-label…), corner, icon and control-height roles, the matte surfaces and elevations, Llama Sans and Llama Mono.
  • Components: every base component of Llama Chat: Alert, AlertDialog, Badge, Button, ButtonGroup, Card, Checkbox, Collapsible, ContextMenu, Dialog, Drawer, DropdownMenu, Empty, HoverCard, Input, Label, Popover, RadioGroup, ScrollArea, Select, Separator, Skeleton, Switch, Table, Tabs, Textarea, Toggle, ToggleGroup and Tooltip. Each is also its own entry point (@ggml-org/llama-ui/ui/dialog), with cn and tv at @ggml-org/llama-ui/utils. Then ActionIcon (an icon button with a tooltip), SearchInput (a search field with a clear button), SyntaxHighlightedCode (code as Llama Chat shows it, in highlight.js's GitHub themes; needs mode-watcher) and Logo (the brand mark, llama-brand's icon), at @ggml-org/llama-ui/app/actions, app/forms, app/content and app/misc. FILTER_TRIGGER_CLASS and FILTER_TOGGLE_ITEM_CLASS style a filters bar the way Llama Chat's Models Manager does.
  • App mockups: MacMenu (Llama for Mac's menu) and WindowsTray (Llama for Windows' tray flyout), the native apps' UIs as the brand's communications draw them, with an annotate snippet to pin a page's numbered callouts to their edges.
  • Model UI: how a model is shown in Llama Chat and on llama.app: ModelCard, ModelFamilyCard (a family as llama.app's catalog shows it), ModelId (name, badges, capability, context and size icons), ModelCapabilityIcons (icons or labelled badges), ModelOrgAvatar, ModelMetadataItem, ModelQuantOptions, ModelQuantChip, ModelQuantRow, ModelDraftSidecars, ModelDownloadProgressBar, plus the formatters and minMemoryTierGb and summarizeSizes, at @ggml-org/llama-ui/models. They take model data in and report what the user did out; fetching and downloading stay in the app.

Next: llama.app's model page.

The constants, enums and code helpers the components use are entry points too, for an app that shows the same things: @ggml-org/llama-ui/constants (the shared classes and code-block constants), @ggml-org/llama-ui/enums (ColorMode, TooltipSide, BooleanString) and @ggml-org/llama-ui/code (highlightCode, trimCodePadding). The model data (constants, enums, formatters and types) comes with the Model UI at @ggml-org/llama-ui/models.

How the apps in this repo use it

Llama Chat does not install the package: it compiles these sources as part of its own build, so a change here shows in the app at once and the app keeps no copy of a component or a token. For that to work:

  • Sources under src/lib import each other by relative path, never through $lib, which in an app points at the app's own src/lib.
  • What they import from npm is listed in dependencies or peerDependencies: the app reads that list to resolve those packages from its own node_modules (ui/apps/chat/scripts/llama-ui.js).
  • Stylesheets import no package. An app imports Tailwind, tw-animate-css and @ggml-org/llama-brand's css/colors.css (the brand's colours, under the names the primitives use) itself, before theme.css.
  • A component added with shadcn-svelte (components.json) arrives with $lib imports: make them relative.

Development

  • npm run storybook: the package's Storybook, with a story for everything it holds; the stories run as tests in npm test, and Llama Chat's Storybook (in ui/apps/chat) shows them under Llama UI
  • npm run dev: Storybook and a small SvelteKit check page (src/routes)
  • npm run check: svelte-check
  • npm run prepack: build the library into dist/ and run publint
  • node scripts/npm-version-check.mjs: what the release workflow would make of this folder, against the real registry

Releases

The package is published from here by ui-lib-publish.yml, which runs when a commit reaches master with ui/lib/ui in it. The version in package.json is the release: land a bump together with the change that should ship and the workflow type-checks, builds, lints and publishes that version to npm, with a provenance attestation. A library change that carries no bump publishes nothing and leaves a warning on the run.

  • npm version <patch|minor> --no-git-tag-version and commit: it moves package.json and both version fields of the lockfile together.
  • Below 1.0: a breaking change bumps the minor, a feature bumps the patch.
  • A version with a prerelease suffix (0.5.0-beta.1) publishes under the next tag, so latest stays a stable build.
  • Publishing needs no token in the repo: the job trades its OIDC identity for one, so the only place to look when a publish is refused is the package's trusted-publisher settings on npm. A publisher names a workflow that must already exist under .github/workflows, so it is added after this workflow lands, and it allows staged publishing until npm publish is permitted for it. Provenance is generated without asking, and only on a GitHub-hosted runner: a self-hosted one cannot publish this way.