@pablozaiden/webapp 1.1.1 → 1.2.0

package/docs/getting-started.md

@@ -4,10 +4,11 @@ Apps are one Bun application: backend routes, websocket, React UI and static ass
 
 ```ts
 import { z } from "zod";
-import { createWebAppServer, defineRoutes, jsonResponse, parseJson } from "@pablozaiden/webapp/server";
+import { createLogger, createWebAppServer, defineRoutes, jsonResponse, parseJson } from "@pablozaiden/webapp/server";
 
 const items: Array<{ id: string; userId: string; title: string }> = [];
 const itemCreateSchema = z.object({ title: z.string() });
+const log = createLogger("items");
 
 const routes = defineRoutes({
   "/api/items": {
@@ -16,7 +17,11 @@ const routes = defineRoutes({
     description: "List or create items.",
     cliPath: "items",
     tags: ["items"],
-    GET: (_req, ctx) => jsonResponse(ctx.filterOwned(items)),
+    GET: (_req, ctx) => {
+      const ownedItems = ctx.filterOwned(items);
+      log.info("Listed items", { count: ownedItems.length });
+      return jsonResponse(ownedItems);
+    },
     async POST(req, ctx) {
       const user = ctx.requireUser();
       const body = await parseJson(req, itemCreateSchema);
@@ -151,49 +156,36 @@ function ThemeAwareRoute() {
 resolved value. Do not inspect or mutate framework-owned root classes or
 attributes to infer theme state.
 
-### Client log-level state
+### Client logging and log-level state
 
-The framework loads the effective client log level as part of the shared
-`WebAppRoot` configuration request. Components rendered inside `WebAppRoot`
-can subscribe with `useLogLevel()`; they should not fetch framework
-configuration or `/api/preferences/log-level` in an app-local initializer:
+Use the shared browser `tslog` service from `@pablozaiden/webapp/web`; do not
+create an application-owned logger or write application logs directly with
+`console.*`:
 
 ```tsx
-import { useEffect } from "react";
-import { useLogLevel } from "@pablozaiden/webapp/web";
-import type { LogLevelName } from "@pablozaiden/webapp/contracts";
-
-function LoggerAdapter({ setLevel }: { setLevel: (level: LogLevelName) => void }) {
-  const { level, fromEnv, loading, error, retry } = useLogLevel();
-
-  useEffect(() => {
-    if (level !== undefined) {
-      setLevel(level);
-    }
-  }, [level, setLevel]);
-
-  if (error) {
-    return <button type="button" onClick={() => void retry()}>Retry log-level configuration</button>;
-  }
-  if (loading || level === undefined) {
-    return null;
-  }
+import { createLogger } from "@pablozaiden/webapp/web";
 
-  return <span aria-hidden="true">{fromEnv ? "Log level is environment-controlled." : null}</span>;
-}
+const projectsLog = createLogger("projects");
+projectsLog.debug("Loaded projects", { count: 12 });
 ```
 
+`WebAppRoot` synchronizes the client logger with the effective level from its
+shared configuration request. The seven levels are `silly`, `trace`, `debug`,
+`info`, `warn`, `error`, and `fatal`; the setting is shared with server
+logging. Use `useLogLevel()` only when UI code needs to display the current
+level or its environment-controlled state. Applications should not fetch
+framework configuration or `/api/preferences/log-level` to configure logging.
+
 `level` and `fromEnv` are unavailable until valid framework configuration has
 loaded. Do not substitute a default level when `error` is set. The framework
-Settings control owns persistence and updates the shared state without a page
-reload; `fromEnv` indicates that the server environment locks the value.
-`LoggerAdapter` remains application-owned and can adapt the state to any
-logging library.
+Settings control owns persistence and updates the shared client and server
+logger levels without a page reload; `fromEnv` indicates that the server
+environment locks the value.
 
 ### In-memory server logs
 
 Admins can enable temporary server-log capture from Developer Settings next to
-the log-level selector. The framework exposes the current state in
+the log-level selector. The shared WebApp server logger exposes the current state in
 `/api/config`; it starts disabled on every process start and is never stored in
 the database. Admin clients can retrieve a bounded chronological snapshot from
 `GET /api/server/logs` after enabling capture. The buffer is limited to the
@@ -293,7 +285,8 @@ The app configures an uppercase `envPrefix`; the framework reads only variables
 | `{PREFIX}_HOST` | `localhost` | Bind host |
 | `{PREFIX}_PORT` | `3000` | Bind port |
 | `{PREFIX}_DATA_DIR` | `./data` | Durable SQLite persistence directory for framework auth and app data |
-| `{PREFIX}_LOG_LEVEL` | `info` | `trace`, `debug`, `info`, `warn`, `error`; locks settings log-level control when set |
+| `{PREFIX}_LOG_LEVEL` | `info` | `silly`, `trace`, `debug`, `info`, `warn`, `error`, `fatal`; locks settings log-level control when set |
+| `{PREFIX}_IN_MEMORY_LOGS` | `false` | Initial value for process-local server-log capture; `true`, `1`, or `yes` enables it |
 | `{PREFIX}_DISABLE_PASSKEY` | unset | Emergency bypass that logs in as the existing owner; it does not create users |
 | `{PREFIX}_DISABLE_SAME_ORIGIN_CHECK` | unset | Development/testing escape hatch |
 | `{PREFIX}_TRUST_PROXY` | `false` | Explicitly trust the documented `X-Forwarded-*` headers; keep disabled for direct deployments |

package/docs/server.md

@@ -138,6 +138,36 @@ the constructor inputs. Do not mutate `app.config` after construction to
 replace constructor options; omit `runtimeConfig` when the framework should read
 the environment itself.
 
+## Server logging
+
+WebApp exposes one server-side `tslog` service for the framework and
+application code. Use the root logger or a cached sub-logger from
+`@pablozaiden/webapp/server`; do not add a second server logger in the app:
+
+```ts
+import { createLogger, log } from "@pablozaiden/webapp/server";
+
+const projectsLog = createLogger("projects");
+
+log.info("Application initialized");
+projectsLog.debug("Loaded projects", { count: 12 });
+```
+
+The available levels, from most to least verbose, are `silly`, `trace`,
+`debug`, `info`, `warn`, `error`, and `fatal`. The effective level is shared by
+the root logger and all cached sub-loggers. It is selected from
+`{PREFIX}_LOG_LEVEL`, a persisted administrator preference, or `info` by
+default, in that order.
+
+Every emitted entry is written through `tslog` to the appropriate stdout or
+stderr stream. When in-memory capture is enabled, the same rendered entries
+from both framework and application loggers are also retained in the
+process-local buffer. Capture is disabled by default and can be initialized
+with `{PREFIX}_IN_MEMORY_LOGS=true`; an administrator can then change the
+runtime toggle from Developer Settings. The environment value is an initial
+value, not a lock, and capture is cleared when disabled or when the process
+starts.
+
 Built-in endpoints include:
 
 | Endpoint | Purpose |
@@ -167,15 +197,36 @@ returns a conflict when the environment controls the value.
 `GET /api/server/logs` is restricted to admin users and returns
 `{ enabled: boolean, logs: ServerLogEntry[] }`. Entries are returned in
 chronological order and contain the timestamp, level, logger scope, message,
-and rendered log line. When capture is disabled, the endpoint returns `200`
-with `enabled: false` and an empty list. `PUT /api/server/logs/settings`
+and the rendered `tslog` line. When capture is disabled, the endpoint returns
+`200` with `enabled: false` and an empty list. `PUT /api/server/logs/settings`
 accepts `{ "enabled": boolean }`, is restricted to admins, and uses the normal
 same-origin policy for browser mutations. API-key and bearer callers continue
 to use the existing token-auth behavior. The in-memory buffer is limited to
 the newest 1,000 entries and 512 KiB of rendered UTF-8 lines; disabling capture
-clears it. These endpoints only expose messages emitted through the framework
+clears it. These endpoints expose entries emitted through the shared WebApp
 logger and never make the logs durable.
 
+## Client logging
+
+WebApp also exposes a browser-side `tslog` service through
+`@pablozaiden/webapp/web`. Use it for application code instead of adding a
+second logger or writing application logs directly with `console.*`:
+
+```tsx
+import { createLogger, log } from "@pablozaiden/webapp/web";
+
+const projectsLog = createLogger("projects");
+
+log.info("Application UI initialized");
+projectsLog.debug("Loaded projects", { count: 12 });
+```
+
+The client service provides the same seven levels as the server service and
+writes to the browser console. `WebAppRoot` automatically synchronizes its
+effective level with the shared framework configuration, including changes
+made from Developer Settings. Client logs are browser-local and are not
+included in the server's `/api/server/logs` snapshot.
+
 Server-side applications that need credentials for internal runtimes should use
 the server-only `createManagedApiKey`, `listManagedApiKeys`, and
 `revokeManagedApiKey` helpers. Managed keys are persisted in the same API-key

package/docs/settings.md

@@ -9,7 +9,7 @@ Settings is framework-owned so apps stay consistent. It includes:
 - Admin user management
 - Admin log-level preference unless `{PREFIX}_LOG_LEVEL` is set
 - Admin in-memory server-log capture toggle; disabled and cleared on process
-  start or when turned off
+  start or when turned off; `{PREFIX}_IN_MEMORY_LOGS` can enable it initially
 - Admin server kill
 - Version/about
 
@@ -36,10 +36,11 @@ the shared hook state after a successful save, and `fromEnv` is true when
 configuration fetch or initializer component.
 
 Developer Settings also includes **Store server logs in memory**. It is an
-admin-only, process-local setting and is disabled when the server starts. When
-enabled, the framework logger retains only the newest 1,000 eligible entries
-within a 512 KiB rendered-line limit; disabling it immediately clears the
-buffer. The setting and captured logs are never stored in SQLite.
+admin-only, process-local setting and is disabled when the server starts unless
+`{PREFIX}_IN_MEMORY_LOGS` is set to `true`, `1`, or `yes`. When enabled, the
+shared `tslog` service retains only the newest 1,000 eligible entries within a
+512 KiB rendered-line limit; disabling it immediately clears the buffer. The
+setting and captured logs are never stored in SQLite.
 
 Security lists only show useful active user credentials. Managed API keys created by
 server-side applications, and their metadata, are not returned by the browser API-key

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pablozaiden/webapp",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Opinionated Bun + React webapp framework for single-server apps",
   "license": "MIT",
   "type": "module",
@@ -49,6 +49,7 @@
     "bun-plugin-tailwind": "0.1.2",
     "jose": "6.2.3",
     "tailwindcss": "4.3.1",
+    "tslog": "4.10.2",
     "zod": "4.4.3"
   },
   "peerDependencies": {

package/src/contracts/index.ts

@@ -1,4 +1,28 @@
-export type LogLevelName = "trace" | "debug" | "info" | "warn" | "error";
+export const VALID_LOG_LEVELS = ["silly", "trace", "debug", "info", "warn", "error", "fatal"] as const;
+
+export type LogLevelName = typeof VALID_LOG_LEVELS[number];
+
+export const LOG_LEVELS: Record<LogLevelName, number> = {
+  silly: 0,
+  trace: 1,
+  debug: 2,
+  info: 3,
+  warn: 4,
+  error: 5,
+  fatal: 6,
+};
+
+export const LOG_LEVEL_NAMES: Record<number, LogLevelName> = {
+  0: "silly",
+  1: "trace",
+  2: "debug",
+  3: "info",
+  4: "warn",
+  5: "error",
+  6: "fatal",
+};
+
+export const DEFAULT_LOG_LEVEL: LogLevelName = "info";
 
 export type ThemePreference = "system" | "light" | "dark";
 

package/src/server/create-web-app-server.ts

@@ -11,7 +11,7 @@ import {
 import { createAuthentication } from "./authentication";
 import { createFrameworkEndpointHandler } from "./framework-endpoints";
 import { createServerLifecycle } from "./server-lifecycle";
-import { inMemoryLogStorage, resetInMemoryLogStorage, setLogLevel } from "./logger";
+import { inMemoryLogStorage, resetInMemoryLogStorage, setInMemoryLogStorageEnabled, setLogLevel } from "./logger";
 import { createWebDocumentProvider, htmlResponse } from "./web-document";
 import { createPublicRouteDispatcher } from "./public-route-dispatch";
 import { createRouteDispatcher } from "./route-dispatch";
@@ -46,6 +46,7 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
     throw new Error("runtimeConfig appName and envPrefix must match the createWebAppServer inputs");
   }
   resetInMemoryLogStorage();
+  setInMemoryLogStorageEnabled(config.inMemoryLogsEnabled);
   const store = input.store ?? sqliteWebAppStore({ dataDir: config.dataDir });
   store.initialize();
   const savedLogLevel = store.getLogLevelPreference();

package/src/server/index.ts

@@ -4,6 +4,17 @@ export * from "./route-catalog";
 export * from "./responses";
 export * from "./public-assets";
 export * from "./create-web-app-server";
+export {
+  DEFAULT_LOG_LEVEL,
+  VALID_LOG_LEVELS,
+  type LogLevelName,
+} from "../contracts";
+export {
+  createLogger,
+  getLogLevel,
+  log,
+  setLogLevel,
+} from "./logger";
 export { getRequestBaseUrl, getRequestOriginInfo, type RequestOriginInfo } from "./auth/request-origin";
 export * from "./auth/api-keys";
 export * from "./auth/store";

package/src/server/logger.ts

@@ -1,21 +1,22 @@
-import type { LogLevelName, ServerLogEntry } from "../contracts";
-
-const ORDER: Record<LogLevelName, number> = {
-  trace: 10,
-  debug: 20,
-  info: 30,
-  warn: 40,
-  error: 50,
-};
+import { inspect } from "node:util";
+import { Logger, type ILogObj, type IMeta } from "tslog";
+import {
+  DEFAULT_LOG_LEVEL,
+  LOG_LEVEL_NAMES,
+  LOG_LEVELS,
+  VALID_LOG_LEVELS,
+  type LogLevelName,
+  type ServerLogEntry,
+} from "../contracts";
 
 export const MAX_IN_MEMORY_LOG_ENTRIES = 1_000;
 export const MAX_IN_MEMORY_LOG_BYTES = 512 * 1024;
 
-let currentLevel: LogLevelName = "info";
 let inMemoryLogStorageEnabled = false;
 let inMemoryLogEntries: ServerLogEntry[] = [];
 let inMemoryLogBytes = 0;
 const textEncoder = new TextEncoder();
+const subLoggers = new Map<string, Logger<ILogObj>>();
 
 export interface InMemoryLogStorage {
   isEnabled(): boolean;
@@ -24,12 +25,8 @@ export interface InMemoryLogStorage {
   reset(): void;
 }
 
-export function setLogLevel(level: LogLevelName): void {
-  currentLevel = level;
-}
-
-export function getLogLevel(): LogLevelName {
-  return currentLevel;
+function isLogLevelName(value: unknown): value is LogLevelName {
+  return typeof value === "string" && VALID_LOG_LEVELS.includes(value as LogLevelName);
 }
 
 function lineByteLength(line: string): number {
@@ -55,6 +52,100 @@ function appendInMemoryLogEntry(entry: ServerLogEntry): void {
   }
 }
 
+function formatValue(value: unknown): string {
+  if (value === undefined) {
+    return "";
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value instanceof Error) {
+    return `${value.name}: ${value.message}`;
+  }
+  if (typeof value === "object" && value !== null && "message" in value) {
+    const record = value as { message?: unknown; name?: unknown };
+    if (typeof record.message === "string") {
+      return typeof record.name === "string" ? `${record.name}: ${record.message}` : record.message;
+    }
+  }
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function appendTslogEntry(metadata: IMeta, line: string, logArgs: unknown[], logErrors: string[]): void {
+  const level = LOG_LEVEL_NAMES[metadata.logLevelId] ?? (metadata.logLevelName.toLowerCase() as LogLevelName);
+  if (!isLogLevelName(level)) {
+    return;
+  }
+  const timestamp = metadata.date.toISOString();
+  const scope = typeof metadata.name === "string" && metadata.name ? metadata.name : "webapp";
+  const message = formatValue(logArgs[0] ?? logErrors[0] ?? "");
+  appendInMemoryLogEntry({
+    timestamp,
+    level,
+    scope,
+    message,
+    line,
+  });
+}
+
+function renderConsoleValue(value: unknown): string {
+  return typeof value === "string" ? value : inspect(value, { colors: false, compact: true, depth: Infinity });
+}
+
+function transportFormatted(logMetaMarkup: string, logArgs: unknown[], logErrors: string[], logMeta?: IMeta): void {
+  const errors = (logErrors.length > 0 && logArgs.length > 0 ? "\n" : "") + logErrors.join("\n");
+  const line = `${logMetaMarkup}${logArgs.map(renderConsoleValue).join(" ")}${errors}`;
+  const level = LOG_LEVEL_NAMES[logMeta?.logLevelId ?? LOG_LEVELS.info] ?? DEFAULT_LOG_LEVEL;
+  if (level === "fatal" || level === "error") {
+    console.error(line);
+  } else if (level === "warn") {
+    console.warn(line);
+  } else {
+    console.log(line);
+  }
+  if (logMeta) {
+    appendTslogEntry(logMeta, line, logArgs, logErrors);
+  }
+}
+
+export const log = new Logger<ILogObj>({
+  name: "webapp",
+  minLevel: LOG_LEVELS[DEFAULT_LOG_LEVEL],
+  prettyLogTimeZone: "UTC",
+  stylePrettyLogs: false,
+  prettyInspectOptions: { colors: false, compact: true, depth: Infinity },
+  overwrite: { transportFormatted },
+});
+
+export function createLogger(scope: string): Logger<ILogObj> {
+  const existing = subLoggers.get(scope);
+  if (existing) {
+    return existing;
+  }
+  const logger = log.getSubLogger({ name: scope });
+  subLoggers.set(scope, logger);
+  return logger;
+}
+
+export function setLogLevel(level: LogLevelName): void {
+  if (!isLogLevelName(level)) {
+    throw new Error(`Invalid log level: ${String(level)}`);
+  }
+  const numericLevel = LOG_LEVELS[level];
+  log.settings.minLevel = numericLevel;
+  for (const subLogger of subLoggers.values()) {
+    subLogger.settings.minLevel = numericLevel;
+  }
+}
+
+export function getLogLevel(): LogLevelName {
+  return LOG_LEVEL_NAMES[log.settings.minLevel] ?? DEFAULT_LOG_LEVEL;
+}
+
 export function setInMemoryLogStorageEnabled(enabled: boolean): void {
   inMemoryLogStorageEnabled = enabled;
   if (!enabled) {
@@ -83,29 +174,3 @@ export const inMemoryLogStorage: InMemoryLogStorage = {
   getEntries: getInMemoryLogEntries,
   reset: resetInMemoryLogStorage,
 };
-
-export function createLogger(scope: string) {
-  function log(level: LogLevelName, message: string, fields?: Record<string, unknown>): void {
-    if (ORDER[level] < ORDER[currentLevel]) {
-      return;
-    }
-    const timestamp = new Date().toISOString();
-    const suffix = fields ? ` ${JSON.stringify(fields)}` : "";
-    const line = `${timestamp}\t${level.toUpperCase()}\t${scope}\t${message}${suffix}`;
-    appendInMemoryLogEntry({ timestamp, level, scope, message, line });
-    if (level === "error") {
-      console.error(line);
-    } else if (level === "warn") {
-      console.warn(line);
-    } else {
-      console.log(line);
-    }
-  }
-  return {
-    trace: (message: string, fields?: Record<string, unknown>) => log("trace", message, fields),
-    debug: (message: string, fields?: Record<string, unknown>) => log("debug", message, fields),
-    info: (message: string, fields?: Record<string, unknown>) => log("info", message, fields),
-    warn: (message: string, fields?: Record<string, unknown>) => log("warn", message, fields),
-    error: (message: string, fields?: Record<string, unknown>) => log("error", message, fields),
-  };
-}

package/src/server/request-schemas.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { VALID_LOG_LEVELS } from "../contracts";
 import type { AuthenticationResponseJSON, RegistrationResponseJSON } from "@simplewebauthn/server";
 
 const nonEmptyString = z.string().min(1);
@@ -140,7 +141,7 @@ export const themePreferenceRequestSchema = z.object({
 });
 
 export const logLevelPreferenceRequestSchema = z.object({
-  level: z.enum(["trace", "debug", "info", "warn", "error"]),
+  level: z.enum(VALID_LOG_LEVELS),
 });
 
 export const inMemoryLogSettingsRequestSchema = z.object({

package/src/server/runtime-config.ts

@@ -1,4 +1,4 @@
-import type { LogLevelName } from "../contracts";
+import { DEFAULT_LOG_LEVEL, VALID_LOG_LEVELS, type LogLevelName } from "../contracts";
 
 export const TRUST_PROXY_HEADERS = ["proto", "host", "prefix"] as const;
 export type TrustProxyHeader = typeof TRUST_PROXY_HEADERS[number];
@@ -18,6 +18,7 @@ export interface RuntimeConfig {
   dataDir: string;
   logLevel: LogLevelName;
   logLevelFromEnv: boolean;
+  inMemoryLogsEnabled: boolean;
   passkeyDisabled: boolean;
   sameOriginDisabled: boolean;
   publicBaseUrl?: string;
@@ -26,10 +27,8 @@ export interface RuntimeConfig {
   development: false | { hmr: true; console: true };
 }
 
-const LOG_LEVELS = new Set<LogLevelName>(["trace", "debug", "info", "warn", "error"]);
-
 function isSupportedLogLevel(value: unknown): value is LogLevelName {
-  return typeof value === "string" && LOG_LEVELS.has(value as LogLevelName);
+  return typeof value === "string" && VALID_LOG_LEVELS.includes(value as LogLevelName);
 }
 
 export function resolveEffectiveLogLevel(
@@ -80,7 +79,7 @@ function parseLogLevel(raw: string | undefined, fallback: LogLevelName, name: st
     return fallback;
   }
   if (!isSupportedLogLevel(raw)) {
-    throw new Error(`${name} must be one of trace, debug, info, warn, error; received "${raw}"`);
+    throw new Error(`${name} must be one of ${VALID_LOG_LEVELS.join(", ")}; received "${raw}"`);
   }
   return raw;
 }
@@ -160,7 +159,8 @@ export function readRuntimeConfig(input: {
 }): RuntimeConfig {
   const envPrefix = assertEnvPrefix(input.envPrefix);
   const logLevelRaw = readEnv(envPrefix, "LOG_LEVEL");
-  const logLevel = parseLogLevel(logLevelRaw, input.defaultLogLevel ?? "info", envName(envPrefix, "LOG_LEVEL"));
+  const logLevel = parseLogLevel(logLevelRaw, input.defaultLogLevel ?? DEFAULT_LOG_LEVEL, envName(envPrefix, "LOG_LEVEL"));
+  const inMemoryLogsEnabled = parseBoolean(readEnv(envPrefix, "IN_MEMORY_LOGS"), false, envName(envPrefix, "IN_MEMORY_LOGS"));
   const publicBaseUrl = parsePublicBaseUrl(readEnv(envPrefix, "PUBLIC_BASE_URL"), envName(envPrefix, "PUBLIC_BASE_URL"));
   const trustProxyEnabled = parseBoolean(readEnv(envPrefix, "TRUST_PROXY"), false, envName(envPrefix, "TRUST_PROXY"));
   const trustProxy = {
@@ -176,6 +176,7 @@ export function readRuntimeConfig(input: {
     dataDir: readEnv(envPrefix, "DATA_DIR") || "./data",
     logLevel,
     logLevelFromEnv: Boolean(logLevelRaw),
+    inMemoryLogsEnabled,
     passkeyDisabled: isTruthyEnv(readEnv(envPrefix, "DISABLE_PASSKEY")),
     sameOriginDisabled: isTruthyEnv(readEnv(envPrefix, "DISABLE_SAME_ORIGIN_CHECK")),
     publicBaseUrl,
@@ -194,6 +195,7 @@ export function safeRuntimeConfig(config: RuntimeConfig): Record<string, unknown
     dataDir: config.dataDir,
     logLevel: config.logLevel,
     logLevelFromEnv: config.logLevelFromEnv,
+    inMemoryLogsEnabled: config.inMemoryLogsEnabled,
     passkeyDisabled: config.passkeyDisabled,
     sameOriginDisabled: config.sameOriginDisabled,
     publicBaseUrl: config.publicBaseUrl,

package/src/web/WebAppRoot.tsx

@@ -11,6 +11,7 @@ import type { HeaderContext, WebAppRootProps } from "./root-types";
 import type { ActionMenuItem, SidebarNode, WebAppRoute } from "./sidebar/types";
 import { ThemeProvider } from "./theme";
 import { WebAppConfigProvider, useWebAppConfig } from "./webapp-config";
+import { setLogLevel } from "./logger";
 
 export { replaceHashRoute, replaceWebAppRoute, routeToHash } from "./routing";
 export type {
@@ -195,6 +196,13 @@ function WebAppRootContent({
 
 function WebAppRootWithConfig(props: WebAppRootProps) {
   const { config, error, refresh } = useWebAppConfig();
+
+  useEffect(() => {
+    if (config) {
+      setLogLevel(config.logLevel.level);
+    }
+  }, [config?.logLevel.level]);
+
   return (
     <ThemeProvider userId={config?.currentUser?.id}>
       <WebAppRootContent {...props} config={config} error={error} refresh={refresh} />

package/src/web/index.ts

@@ -11,5 +11,6 @@ export { useTheme } from "./theme";
 export type { ResolvedTheme, WebAppThemeState } from "./theme";
 export { useLogLevel } from "./log-level";
 export type { WebAppLogLevelState } from "./log-level";
+export { createLogger, getLogLevel, log } from "./logger";
 export { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 export type { ThemePreference } from "../contracts";

package/src/web/logger.ts

@@ -0,0 +1,44 @@
+import { Logger, type ILogObj } from "tslog";
+import {
+  DEFAULT_LOG_LEVEL,
+  LOG_LEVEL_NAMES,
+  LOG_LEVELS,
+  VALID_LOG_LEVELS,
+  type LogLevelName,
+} from "../contracts";
+
+const subLoggers = new Map<string, Logger<ILogObj>>();
+
+function isLogLevelName(value: unknown): value is LogLevelName {
+  return typeof value === "string" && VALID_LOG_LEVELS.includes(value as LogLevelName);
+}
+
+export const log = new Logger<ILogObj>({
+  name: "webapp",
+  minLevel: LOG_LEVELS[DEFAULT_LOG_LEVEL],
+});
+
+export function createLogger(scope: string): Logger<ILogObj> {
+  const existing = subLoggers.get(scope);
+  if (existing) {
+    return existing;
+  }
+  const logger = log.getSubLogger({ name: scope });
+  subLoggers.set(scope, logger);
+  return logger;
+}
+
+export function setLogLevel(level: LogLevelName): void {
+  if (!isLogLevelName(level)) {
+    throw new Error(`Invalid log level: ${String(level)}`);
+  }
+  const numericLevel = LOG_LEVELS[level];
+  log.settings.minLevel = numericLevel;
+  for (const subLogger of subLoggers.values()) {
+    subLogger.settings.minLevel = numericLevel;
+  }
+}
+
+export function getLogLevel(): LogLevelName {
+  return LOG_LEVEL_NAMES[log.settings.minLevel] ?? DEFAULT_LOG_LEVEL;
+}

package/src/web/settings/account-section.tsx

@@ -1,14 +1,12 @@
 import { useState } from "react";
-import type { LogLevelName, WebAppConfigResponse } from "../../contracts";
+import { VALID_LOG_LEVELS, type LogLevelName, type WebAppConfigResponse } from "../../contracts";
 import { appJson } from "../api-client";
 import { Badge, Button, CheckboxField, ErrorState, FormSection, LoadingState, SelectField } from "../components";
 import { useLogLevel } from "../log-level";
 import { isThemePreference, useTheme } from "../theme";
 
-const LOG_LEVEL_NAMES = ["trace", "debug", "info", "warn", "error"] as const satisfies readonly LogLevelName[];
-
 function isLogLevelName(value: string): value is LogLevelName {
-  return LOG_LEVEL_NAMES.some((level) => level === value);
+  return VALID_LOG_LEVELS.some((level) => level === value);
 }
 
 export interface AccountSectionProps {
@@ -102,7 +100,7 @@ export function AccountSection({ config, refresh, setError }: AccountSectionProp
               disabled={logLevel.fromEnv === true || logLevel.loading || logLevelSaving}
               onChange={(event) => void updateLogLevel(event.currentTarget.value)}
             >
-              {LOG_LEVEL_NAMES.map((level) => <option key={level} value={level}>{level}</option>)}
+              {VALID_LOG_LEVELS.map((level) => <option key={level} value={level}>{level}</option>)}
             </SelectField>
           ) : null}
           <CheckboxField

package/src/web/webapp-config.tsx

@@ -1,5 +1,5 @@
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
-import type { WebAppConfigResponse } from "../contracts";
+import { VALID_LOG_LEVELS, type WebAppConfigResponse } from "../contracts";
 import { appJson } from "./api-client";
 
 export interface WebAppConfigState {
@@ -16,7 +16,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 }
 
 function isLogLevelName(value: unknown): boolean {
-  return value === "trace" || value === "debug" || value === "info" || value === "warn" || value === "error";
+  return typeof value === "string" && VALID_LOG_LEVELS.includes(value as WebAppConfigResponse["logLevel"]["level"]);
 }
 
 function isCurrentUser(value: unknown): boolean {