XMLUI Config Reference

xmluiConfig is the home for framework and runtime settings that change how the XMLUI engine behaves. Use it for routing mode, inline-style handling, validation severity, XMLScript diagnostics, and other runtime-level switches.

Application-specific values belong under appGlobals. appGlobals is exposed to markup as the global identifier appGlobals; xmluiConfig is read by the framework and is not exposed as a separate global.

When the engine looks up a runtime setting, it reads a merged view where xmluiConfig overrides the same key in appGlobals, and any key not set in xmluiConfig falls back to appGlobals. This keeps existing apps working while giving new apps a dedicated place for runtime settings.

Deprecation notice: placing framework / runtime settings under appGlobals is still supported today via the fallback mechanism, but this behaviour will be deprecated in an upcoming minor release. Move framework settings such as apiUrl, headers, notifications, prefetchedContent, showHeadingAnchors, useHashBasedRouting, disableInlineStyle, xsVerbose, and the strict* family to xmluiConfig. Application-specific values remain under appGlobals.

// config.ts (Vite / built mode)
const App: StandaloneAppDescription = {
  name: "My App",
  appGlobals: {
    currentUser: { displayName: "Ada" },
  },
  xmluiConfig: {
    apiUrl: "https://api.example.com",
    headers: { "X-App-Version": "1.0.0" },
    useHashBasedRouting: false,
    disableInlineStyle: false,
    lintSeverity: "warning",
    xsVerbose: false,
  },
};

// config.json (standalone / buildless mode)
{
  "appGlobals": {
    "currentUser": { "displayName": "Ada" }
  },
  "xmluiConfig": {
    "apiUrl": "https://api.example.com",
    "useHashBasedRouting": false,
    "lintSeverity": "warning"
  }
}

Component authors should use useXmluiConfig() for framework / runtime settings. It returns the merged read-only view (xmluiConfig overlaying appGlobals). Use useAppGlobals() only for raw application-specific values.

Quick reference

Keys in this table are read through the merged compatibility view, so placing them under appGlobals continues to work for now. Prefer xmluiConfig for all new code.

Settings

apiUrl

apiUrl?: string;

The base URL prepended to all relative API request URLs. When set, data sources, API calls, file actions, and managed fetches that use a relative URL, such as /api/contacts, are resolved against this base.

xmluiConfig: {
  apiUrl: "https://api.example.com",
}

applyLayoutProperties

applyLayoutProperties?: "all" | "dims" | "spacing" | "none";

Controls which layout properties the rendering engine applies to components. This restriction applies to both base properties, such as backgroundColor, and responsive variants, such as backgroundColor-lg. It is useful when embedding XMLUI into a host application that manages its own layout.

xmluiConfig: {
  applyLayoutProperties: "spacing",
}

defaultToOptionalMemberAccess

defaultToOptionalMemberAccess?: boolean; // default: true

When true, property access expressions in XMLScript use optional chaining semantics. Accessing a property of undefined or null returns undefined instead of throwing an error. Set to false to use strict member access and surface access errors explicitly.

xmluiConfig: {
  defaultToOptionalMemberAccess: false,
}

blog

blog?: {
  posts: BlogPost[];
};

Configuration for the Blog component. Must contain at least a posts array of blog post objects. Additional layout behavior, table of contents, and tag display are controlled via theme variables on the Blog component.

codeHighlighter

codeHighlighter?: CodeHighlighter;

An object conforming to the CodeHighlighter interface that provides syntax highlighting for code blocks inside Markdown and CodeFence components. When not set, code blocks are rendered as plain text unless a global browser highlighter is present.

columnCanSortDefault

columnCanSortDefault?: boolean;

Overrides the default canSort value for Column components that do not set canSort explicitly.

xmluiConfig: {
  columnCanSortDefault: false,
}

disableInlineStyle

disableInlineStyle?: boolean; // default: false

When true, inline style properties such as backgroundColor, color, and padding set directly on components in markup are not applied. Dimension-related properties (width, height, and their min/max variants) are still applied because they participate in flex layout. Use this when the host application manages styling exclusively through its own CSS.

Individual Theme components can override this per-subtree via their own disableInlineStyle property.

xmluiConfig: {
  disableInlineStyle: true,
}

errorResponseTransform

errorResponseTransform?: string;

An XMLScript expression that transforms API error responses before XMLUI surfaces them. The expression receives the response as $response.

{
  "xmluiConfig": {
    "errorResponseTransform": "{ $response.message || $response.error || 'Request failed' }"
  }
}

headers

headers?: Record<string, string>;

A dictionary of HTTP headers added to outgoing API requests. Headers specified per request override these defaults.

xmluiConfig: {
  headers: {
    Authorization: "Bearer my-token",
    "X-App-Version": "1.0.0",
  },
}

lintSeverity

lintSeverity?: "warning" | "error" | "strict" | "skip"; // default: "warning"

Controls how standalone startup validation issues are shown in the browser. These issues come from the type-contract verifier, such as unknown props, invalid literal values, missing required props, unknown events, and unknown exposed methods.

xmluiConfig: {
  lintSeverity: "error",
}

logRestApiErrors

logRestApiErrors?: boolean; // default: false

When true, REST API response parsing errors are logged to the browser console. This is useful during development when diagnosing unexpected API response shapes.

xmluiConfig: {
  logRestApiErrors: true,
}

notifications

notifications?: {
  duration?: number;
  position?: "top-start" | "top-center" | "top-end" | "bottom-start" | "bottom-center" | "bottom-end";
};

Configuration for toast notifications.

xmluiConfig: {
  notifications: {
    duration: 5000,
    position: "top-end",
  },
}

prefetchedContent

prefetchedContent?: Record<string, string>;

A dictionary mapping URL paths to pre-fetched content strings. XMLUI data loading checks this map before it needs fetched content, which helps avoid redundant network requests for content already available at startup.

xmluiConfig: {
  prefetchedContent: {
    "/pages/home.md": "# Welcome",
  },
}

searchIndexEnabled

searchIndexEnabled?: boolean; // default: false

When true, the Pages component walks all Page children at startup and builds an in-memory search index. This is required for full-text search to work in apps that use the search components.

xmluiConfig: {
  searchIndexEnabled: true,
}

showHeadingAnchors

showHeadingAnchors?: boolean; // default: false

When true, heading components (H1-H6) and markdown headings display a clickable anchor icon that lets users link directly to that heading. Individual headings can override this with their own showAnchor or showHeadingAnchors property.

xmluiConfig: {
  showHeadingAnchors: true,
}

syncExecutionTimeout

syncExecutionTimeout?: number; // default: 1000ms

Affects the synchronous expression execution timeout for bindings in markup attributes. If an expression times out, an error is thrown.

xmluiConfig: {
  syncExecutionTimeout: 500,
}

useHashBasedRouting

useHashBasedRouting?: boolean; // default: true (standalone mode)

Selects the routing strategy used by the app.

xmluiConfig: {
  useHashBasedRouting: false,
}

withXSRFToken

withXSRFToken?: boolean; // default: true

When true, the engine reads the XSRF-TOKEN cookie and includes it as an X-XSRF-TOKEN header on all same-origin API requests. Set to false to disable this behavior if your backend does not use XSRF token validation.

xmluiConfig: {
  withXSRFToken: false,
}

xsVerbose

xsVerbose?: boolean; // default: false

When true, the engine emits detailed diagnostic logs for XMLScript expression evaluation and data loader activity to the browser console. This is useful for debugging reactive data flows and script execution.

xmluiConfig: {
  xsVerbose: true,
}

xsVerboseLogMax

xsVerboseLogMax?: number; // default: 200

Limits the number of log entries emitted when xsVerbose is true. This prevents the console from being overwhelmed in apps with many reactive expressions.

xmluiConfig: {
  xsVerbose: true,
  xsVerboseLogMax: 50,
}

Managed React settings

Managed React features use xmluiConfig for their framework/runtime switches. The detailed behavior is documented in the Managed React articles; this table is the central placement and default reference.

strictBuildValidation is discussed in Build Validation Analyzers. Build-time strictness is currently selected through the CLI or Vite plugin; the xmluiConfig.strictBuildValidation name is reserved for the app-wide switch described there.