Frontend runtime API

Cove loads extension frontend bundles as ESM and provides a versioned set of host modules. Import from this runtime instead of bundling another copy of React or reaching into Cove’s internal source tree.

The current runtime contract is v1. Cove supplies that value in the aggregated UI manifest; UIManifestBuilder.WithRuntimeVersion does not select a different runtime. Treat every import not listed on this page as private implementation detail.

Runtime modules

Use the @cove/runtime/* specifiers in extension source:

Module	Provides
@cove/runtime/react	React
@cove/runtime/react-dom	React DOM
@cove/runtime/react-dom-client	React DOM client APIs
@cove/runtime/react-jsx-runtime	Production JSX runtime
@cove/runtime/react-jsx-dev-runtime	Development JSX runtime
@cove/runtime/react-query	TanStack Query
@cove/runtime/lucide-react	Lucide React icons
@cove/runtime/components	Cove’s public shared component and hook barrel
@cove/runtime/api	Authenticated requests to Cove APIs

Cove still maps the corresponding bare third-party specifiers for older bundles, but new bundles should use the namespaced runtime imports. Configure the extension build to leave runtime modules external so Cove and the extension share the same React tree and host libraries.

Authenticated API requests

Import extensionFetch from the API module:

import { extensionFetch } from "@cove/runtime/api";

export async function loadSummary() {
  const response = await extensionFetch("/api/ext/com.example.reports/summary");
  if (!response.ok) {
    throw new Error(`Request failed with ${response.status}`);
  }

  return response.json();
}

Its signature is:

function extensionFetch(input: string, init?: RequestInit): Promise<Response>;

extensionFetch accepts only same-origin URLs whose path is /api or starts with /api/. Relative forms such as api/ext/... are normalized against the current Cove origin. Cross-origin URLs and non-API paths throw a TypeError before a request is sent.

The helper sends the current bearer or share credentials, uses Cove’s normal access-token refresh and single retry behavior, and returns the standard Response. It forces redirect: "error" so an API request cannot follow a redirect outside the allowed boundary.

Authentication transport does not grant access. Protect the extension endpoint with the appropriate server-side convention from Extension permissions, and handle expected 401, 403, and application errors in the component.

Shared components

Import public UI building blocks from one barrel:

import {
  MediaDetailLayout,
  DetailListToolbar,
  DetailListPagination,
  RelatedEntityListView,
  TagBadge,
} from "@cove/runtime/components";

The v1 barrel groups these exports:

Area	Public exports
Detail and list composition	MediaDetailLayout, DetailListToolbar, DetailListPagination, ListPage, RelatedEntityListView, getRelatedEntityDisplayModes, FilterButton, FilterDialog, VIDEO_CRITERIA, BulkEditDialog, getDefaultFilter, Pager, VIDEO_SORT_OPTIONS
Entity display and media	PopoverButton, VideoCardPopovers, PerformerTile, VideoCard, VideoTile, ImageTile, VideoPlayer, Lightbox
Forms and dialogs	ConfirmDialog, EditModal, Field, TextInput, TextArea, NumberInput, SelectInput, SaveButton, ImageInput
Ratings	InteractiveRating, RatingBadge, RatingBanner, RatingField, getRatingBannerColor, convertToRatingFormat, convertFromRatingFormat, formatDisplayRating, getRatingMax, getRatingStep, getRatingInputLabel, normalizeRatingOptions, defaultRatingSystemOptions
Utilities and custom fields	TagBadge, formatDuration, formatFileSize, formatDate, getResolutionLabel, CustomFieldsDisplay, CustomFieldsEditor
Host integration	openTutorialStoryboard, registerManualContext, useManualContext, useMultiSelect, useKeySequence, useListUrlState, useAppConfig
Types	MediaDetailLayoutProps, MediaDetailTab, MediaDetailSectionProps, LightboxImage, DisplayMode, CriterionDefinition, TutorialOpenRequest, FindFilter

The table groups helper families for readability. Check the matching runtime type declarations when a helper has several arguments.

Native detail layout

MediaDetailLayout gives extension pages the same responsive shell used by Cove detail pages. Its required title prop accepts a React node. Optional props cover:

• navigation with backLabel and onGoBack
• the media region, its aspect ratio and position, sticky behavior, and full-bleed rendering
• a header image, actions, and engagement controls
• sidebar or header tabs with an active key and change callback
• keyboard shortcuts, loading state, errors, and child content

MediaDetailTab describes each tab with a stable key, label, and optional icon, count, disabled state, and manual contexts. MediaDetailSectionProps is the small typed wrapper contract for section children and an optional class name.

Native detail lists

DetailListToolbar composes Cove’s result count, search, sorting, filter dialog, saved filters, selection controls, display modes, zoom, and paging controls around a FindFilter. Supply only the capabilities the embedded list supports; the required props are filter, onFilterChange, totalCount, and sortOptions.

Use DetailListPagination when the pager belongs below the results instead of inside the toolbar:

<DetailListPagination
  filter={filter}
  onFilterChange={setFilter}
  totalCount={totalCount}
/>

It also accepts allowInfinitePageSize, infinitePageSizeOnly, showPagingControls, and className.

These primitives provide Cove’s current UI behavior, but the extension still owns its data query, empty and error states, and permission handling. Prefer host CSS variables and shared components over copying internal markup or Tailwind classes that are not part of this barrel.

Compatibility

Runtime modules are a host contract, not dependencies embedded in the extension archive. Set minCoveVersion to the oldest Cove release on which every imported runtime export has been tested. Adding an import introduced by a newer Cove release raises that practical compatibility floor even when the extension’s backend contract is unchanged.

Keep a package’s frontend imports and its declared compatibility floor in sync, then test installation and the rendered contribution on that minimum version. See Package an extension for how installers enforce minCoveVersion and UI extension points for where components can be mounted.