LLM Reference: VextroConfig & Utilities

This is a dense reference for LLMs. It documents the VextroConfig type, storage system, upload configuration, i18n, and frontend content rendering utilities.

VextroConfig

The main configuration object passed to createVextroClient() and used throughout the admin app.

type VextroConfig = {
  brandName: string;
  logoUrl?: string;
  supportUrl?: string;
  navigation?: Array<VextroNavItem>;
  workspaces?: Array<VextroWorkspaceItem>;
  basePath?: string;
  collectionGroups?: Array<VextroCollectionGroup>;
  ungroupedLabel?: string;
  auth?: VextroAuthConfig;
  inputOverrides?: VextroInputOverrides;
  createBlockEndpoint?: string;
  storage?: VextroStorageConfig;
  upload?: VextroUploadGlobalConfig;
  locale?: VextroLocaleOverrides;
  plugins?: VextroPlugin[];
  richText?: {
    allowRelativeLinks?: boolean;
    toolbar?: RichTextToolbar;
  };
  scope?: {
    types: string[];
    defaultType?: string;
    labels?: Record<string, string>;
    defaultScopeFilter?: boolean;
  };
  accessControlSections?: VextroAccessControlSectionsConfig;
  autoSave?: {
    enabled?: boolean;
    debounceMs?: number;
  };
  presenceLabelFn?: (user: { userId: string; userName: string; userEmail?: string }) => string;
  accessControl?: {
    builtInUI?: boolean;
    labels?: {
      sectionTitle?: string;
      users?: { singular?: string; plural?: string };
      roles?: { singular?: string; plural?: string };
    };
  };
};

VextroConfig Options Table

Field	Type	Default	Description
brandName	string	required	Displayed in sidebar header and login page.
logoUrl	string	—	URL to brand logo image.
supportUrl	string	—	Link to support/help resources.
navigation	VextroNavItem[]	—	Custom navigation items { label, href }.
workspaces	VextroWorkspaceItem[]	—	Workspace switcher items { label, href }.
basePath	string	""	URL prefix for admin routes (e.g., "/admin").
collectionGroups	VextroCollectionGroup[]	—	Sidebar grouping: { label, slugs: string[] }.
ungroupedLabel	string	"Collections"	Label for ungrouped collections in sidebar.
auth	VextroAuthConfig	—	Authentication configuration.
inputOverrides	VextroInputOverrides	—	Custom field input components.
createBlockEndpoint	string	"/api/admin/blocks/create"	API endpoint for block creation.
storage	VextroStorageConfig	—	Storage adapter configuration.
upload	VextroUploadGlobalConfig	—	Global upload settings.
locale	VextroLocaleOverrides	—	i18n overrides merged with English defaults.
plugins	VextroPlugin[]	—	Plugins to register.
richText.allowRelativeLinks	boolean	false	Allow relative URLs in rich text link dialog.
richText.toolbar	RichTextToolbar	—	Default toolbar config for all rich text fields.
scope.types	string[]	—	Available scope types (e.g., ["region"]).
scope.defaultType	string	—	Default scope type when none specified.
scope.labels	Record<string, string>	—	Human-readable labels for scope types.
scope.defaultScopeFilter	boolean	true	Filter relationships by active scope by default.
accessControlSections	VextroAccessControlSectionsConfig	—	Custom sections injected into user/role detail pages. See below.
autoSave.enabled	boolean	—	Enable auto-save on all edit forms.
autoSave.debounceMs	number	—	Debounce delay in milliseconds before auto-saving (default: 2000).
presenceLabelFn	(user) => string	—	Custom function deriving the label shown in field-level presence badges. Defaults to initials (e.g., “John Doe” → “JD”).
accessControl.builtInUI	boolean	true	When false, hides the built-in Access Control section from the sidebar entirely.
accessControl.labels.sectionTitle	string	"Access Control"	Override the sidebar section heading.
accessControl.labels.users	{ singular, plural }	—	Override user-related link labels (e.g., { singular: "Member", plural: "Members" }).
accessControl.labels.roles	{ singular, plural }	—	Override role-related link labels (e.g., { singular: "Group", plural: "Groups" }).

VextroAuthConfig

type VextroAuthConfig = {
  providerId?: string;
  callbackPath?: string;
  authPath?: string;
  title?: string;
  description?: string;
  buttonLabel?: string;
};

Field	Type	Default	Description
providerId	string	—	OAuth provider identifier.
callbackPath	string	—	OAuth callback route path.
authPath	string	—	Base path for auth API routes.
title	string	—	Login page title.
description	string	—	Login page description text.
buttonLabel	string	—	Login button text.

VextroInputOverrides

type VextroInputOverrides = {
  components?: Record<string, VextroInputComponent>;
  context?: Record<string, unknown>;
};

Allows replacing built-in field input components with custom implementations keyed by field type name.

VextroAccessControlSectionsConfig

Extension points for injecting custom Svelte components into the built-in Access Control pages.

type VextroAccessControlSectionsConfig = {
  userDetail?: VextroAccessControlSection<VextroUserDetailSectionPosition>[];
  roleDetail?: VextroAccessControlSection<VextroRoleDetailSectionPosition>[];
};

type VextroAccessControlSection<TPosition = string> = {
  slug: string;
  label: string;
  component: unknown;  // Svelte component
  position: TPosition;
  priority?: number;   // lower renders first at the same position (default: 0)
  chrome?: boolean;    // false = render without card wrapper (default: true)
};

// Valid positions for userDetail sections
type VextroUserDetailSectionPosition =
  | "before-info" | "after-info"
  | "before-status" | "after-status"
  | "before-roles" | "after-roles";

// Valid positions for roleDetail sections
type VextroRoleDetailSectionPosition =
  | "before-users" | "after-users"
  | "before-permissions" | "after-permissions"
  | "before-details" | "after-details"
  | "tab";

Section Component Props

Custom section components receive different props depending on the page they are injected into:

// Props received by userDetail section components
type VextroUserDetailSectionProps = {
  userId: string;
  basePath: string;
};

// Props received by roleDetail section components
type VextroRoleDetailSectionProps = {
  roleId: string;
  basePath: string;
};

Example

import MyUserAuditLog from './MyUserAuditLog.svelte';
import MyRoleCapabilities from './MyRoleCapabilities.svelte';

const config: VextroConfig = {
  brandName: 'My Admin',
  accessControlSections: {
    userDetail: [
      {
        slug: 'audit-log',
        label: 'Audit Log',
        component: MyUserAuditLog,
        position: 'after-roles',
        priority: 0,
      },
    ],
    roleDetail: [
      {
        slug: 'capabilities',
        label: 'Capabilities',
        component: MyRoleCapabilities,
        position: 'tab',
      },
    ],
  },
};

VextroStorageConfig

type VextroStorageConfig = {
  default: VextroStorageAdapter;
  adapters?: Record<string, VextroStorageAdapter>;
};

Field	Type	Description
default	VextroStorageAdapter	Default adapter used by all upload collections.
adapters	Record<string, VextroStorageAdapter>	Named adapters for per-collection override.

VextroStorageAdapter Interface

Storage adapters must implement:

type VextroStorageAdapter = {
  name: string;
  upload: (file: File, options: UploadOptions) => Promise<UploadResult>;
  delete: (storageRef: string) => Promise<void>;
  getUrl: (storageRef: string) => string | Promise<string>;
};

S3AdapterConfig

type S3AdapterConfig = {
  bucket: string;
  region: string;
  accessKeyId: string;
  secretAccessKey: string;
  endpoint?: string;
  prefix?: string;
  publicUrl?: string;
  forcePathStyle?: boolean;
};

VextroUploadGlobalConfig

type VextroUploadGlobalConfig = {
  maxFileSize?: number;        // bytes, default 10MB
  restrictedMimeTypes?: string[];
};

UploadConfig (per-collection)

type UploadConfig = {
  mimeTypes?: string[];
  maxFileSize?: number;
  imageSizes?: ImageSizeConfig[];
  formatOptions?: FormatOptions;
  storageAdapter?: string;
  prefix?: string;
  disableLocalURL?: boolean;
  adminThumbnail?: string;
  focalPoint?: boolean;
  crop?: boolean | { aspectRatios?: string[] };
};

ImageSizeConfig

type ImageSizeConfig = {
  name: string;
  width?: number;
  height?: number;
  fit?: "cover" | "contain" | "fill" | "inside" | "outside";
  position?: string;
  format?: "webp" | "avif" | "jpeg" | "png" | "original";
  quality?: number;
  withoutEnlargement?: boolean;
};

createVextroClient

function createVextroClient(options: VextroClientOptions): VextroClientOptions;

type VextroClientOptions = {
  convexUrl: string;
  config: VextroConfig;
};

A pass-through factory that validates and returns the config. Used in admin app configuration.

Content Rendering Utilities

Exported from "vextro/content" or "vextro".

renderTipTapToHtml

function renderTipTapToHtml(doc: TipTapDoc | RichTextContent): string;

Converts TipTap JSON content to an HTML string for frontend rendering.

extractPlainText

function extractPlainText(doc: TipTapDoc | RichTextContent): string;

Extracts plain text from TipTap JSON, stripping all formatting.

buildSrcSet

function buildSrcSet(variants: ImageVariant[]): string;

Builds a srcset attribute string from image size variants.

buildImageSizes

function buildImageSizes(variants: ImageVariant[]): string;

Builds a sizes attribute string from image size variants.

focalPointToObjectPosition

function focalPointToObjectPosition(focalX: number, focalY: number): string;

Converts focal point coordinates (0-100) to a CSS object-position value.

Additional Image Utilities

function groupVariantsByFormat(variants: ImageVariant[]): Map<string, ImageVariant[]>;
function hasModernFormat(variants: ImageVariant[]): boolean;
function getLargestVariant(variants: ImageVariant[]): ImageVariant | undefined;
function getSmallestVariant(variants: ImageVariant[]): ImageVariant | undefined;

Version Diff Utilities

Exported from "vextro".

function diffDocuments(a: Record<string, unknown>, b: Record<string, unknown>): FieldDiff[];
function diffRichText(a: TipTapDoc, b: TipTapDoc): RichTextDiff;
function diffJson(a: unknown, b: unknown): JsonDiff;
function diffText(a: string, b: string): TextDiffSegment[];
function isDeepEqual(a: unknown, b: unknown): boolean;

i18n System

createI18n

function createI18n(overrides?: VextroLocaleOverrides): void;

Initializes the i18n system with optional overrides merged into the English defaults.

t (translate)

function t(key: string, params?: Record<string, string | number>): string;

Returns the localized string for a key with optional parameter interpolation.

defineLocale

function defineLocale(locale: VextroLocale): VextroLocale;

Type-safe factory for defining a complete locale. Useful for creating full translations.

getLocale

function getLocale(): VextroLocale;

Returns the current active locale object.

Workflow Types

type WorkflowConfig = {
  enabled: boolean;
  stages: WorkflowStageDefinition[];
};

type WorkflowStageDefinition = {
  name: string;
  label: string;
  color?: string;
  requiredRole?: string;
  autoTransition?: {
    afterApprovals?: number;
  };
};

Workflow stages define multi-editor approval chains for content collections. Each stage can require a specific role and auto-advance after a set number of approvals.