@chamvi/ui

The dashboard, served by @chamvi/http. The public API of packages/ui/src/index.ts; the app itself is a prebuilt bundle in dist/app.

npm install @chamvi/ui @chamvi/http @chamvi/core --save

@chamvi/core and @chamvi/http are peer dependencies. See Dashboard for the pages, sign-in and serving rules.

uiRoutes

function uiRoutes(options?: UiRoutesOptions): HttpRoute[];

One unauthenticated, not rate-limited GET prefix route at basePath for createHttpApp({ routes }). Throws InvalidAgentDefinitionError for a basePath that is not a lower-case path, an auth.authup.url that is no absolute http(s) URL, an empty clientId, auth.tokens: false without auth.authup, and an empty root.

/*
 * Copyright (c) 2026.
 * Author Peter Placzek (tada5hi)
 * For the full copyright and license information,
 * view the LICENSE file that was distributed with this source code.
 */

import type { UiAuthupConfig } from '../config/types.ts';

export type UiRoutesOptions = {
    /** The dashboard's path under the app's `basePath` (lower case). Default `/ui`. */
    basePath?: string;
    auth?: {
        /** Offer the token-paste sign-in. Default `true`. */
        tokens?: boolean;
        authup?: UiAuthupConfig;
    };
    /** The build folder. Default the package's `dist/app`. */
    root?: string;
};

/** One file of the build. */
export type BuildFile = {
    bytes: Uint8Array;
    type: string;
    /** Under `assets/`: content-hashed, cached for a year. */
    immutable: boolean;
};

Config

The block uiRoutes() injects into index.html (element id CONFIG_ELEMENT_ID).

/*
 * Copyright (c) 2026.
 * Author Peter Placzek (tada5hi)
 * For the full copyright and license information,
 * view the LICENSE file that was distributed with this source code.
 */

export type UiAuthupConfig = {
    /** The authup API URL, e.g. `https://auth.example.com/api`. */
    url: string;
    /** The authup client the dashboard signs in as (code flow with PKCE). */
    clientId: string;
    realmId?: string;
};

/** What the server injects into `index.html` for the SPA. */
export type UiConfig = {
    /** The chamvi API base (the app's `basePath`, `''` by default). */
    apiBase: string;
    /** Where the dashboard is mounted, e.g. `/ui`. */
    uiBase: string;
    auth: {
        /** Offer the token-paste sign-in (static bearer tokens). */
        tokens: boolean;
        authup?: UiAuthupConfig;
    };
};

Constants

Constant	Value
DEFAULT_UI_BASE_PATH	'/ui'
ASSET_CACHE_CONTROL	'public, max-age=31536000, immutable'
DOCUMENT_CACHE_CONTROL	'no-cache'
CONFIG_ELEMENT_ID	'chamvi-config'

Module

// @chamvi/ui/module, needs @chamvi/app
function uiModule(options?: UiModuleOptions): IModule; // name UI_MODULE_NAME 'chamvi:ui'

Contributes uiRoutes() to the app's routes (/ui under CHAMVI_BASE_PATH). Reads CHAMVI_UI_AUTHUP_CLIENT_ID, CHAMVI_UI_AUTHUP_REALM_ID and AUTHUP_URL from options.env ?? process.env when it is called, unless auth is given. It provides no context (tools have nothing to reach). @chamvi/app is an optional peer: the main entry never imports it.

/*
 * Copyright (c) 2026.
 * Author Peter Placzek (tada5hi)
 * For the full copyright and license information,
 * view the LICENSE file that was distributed with this source code.
 */

import type { Env } from '@chamvi/app';
import type { UiRoutesOptions } from '../routes/types.ts';

/** `uiRoutes()` options; `auth` defaults to the token login plus authup from env. */
export type UiModuleOptions = UiRoutesOptions & {
    /** Default `process.env`, read when the factory is called. */
    env?: Env;
};