Runtime Fetch Component Catalogs

We need to first need to know few things:

CATALOG_API = "/api/runtime-catalog" ARTIFACTS_ORIGIN=https://pub-xxxxxxxxxxxxxxxxxxx.r2.dev (opens in a new tab)

From our host app we gonna hit to the api route CATALOG_API

we gonna call getCachedRuntimeCatalog()

then we will call buildRuntimeCatalog() with nextjs unstable cache

then we call buildCatalogFromPackages() which will return the CatalogEntry we are trying to fetch

we have catalog.json file locally in the host app :

{
  "defaultExternals": [
    "react",
    "react-dom",
    "react/jsx-runtime",
    "react/jsx-dev-runtime",
    "next",
    "next/image",
    "next/link",
    "next/navigation",
    "@xsite/common",
    "@xsite/common/client",
    "@xsite/common/server",
    "@xsite/core",
    "lucide-react"
  ],
  "packages": [
    {
      "id": "about1",
      "label": "About 1",
      "package": "@xsite/ui-about1",
      "version": "1.0.8",
      "category": "about"
    },
    {
      "id": "about2",
      "label": "About 2",
      "package": "@xsite/ui-about2",
      "version": "1.0.9",
      "category": "about"
    },
}

then we need to load package's artifacts

here we fetch each json like

descriptor.json
data.json
schema.json
puck.json
meta.json

and returns in this format


(alias) type PackageArtifacts = {
descriptor: PackageDescriptor;
data: Record<string, unknown> | null;
puck: {
$source?: string;
title?: string;
type?: string;
properties?: Record<string, unknown>;
} | null;
meta: Record<string, unknown> | null;
schema: Record<string, unknown> | null;
urls: {
descriptor: string;
data: string;
puck: string;
meta: string;
schema: string;
module: string;
};
}

the buildCatalogFromPackages() will return the CatalogEntry which is like


{
  "id": "ui.accordion1",
  "alias": "@xsite/ui/accordion1",
  "package": "@xsite/ui-accordion1",
  "version": "0.0.3",
  "status": "active",
  "hostApi": ">=1 <2",
  "category": "accordion",
  "owner": "web-platform",
  "peers": [
    "react@19",
    "react-dom@19",
    "next@14+",
    "@xsite/common"
  ],
  "renderMode": "client",
  "module": {
    "path": "./index.mjs",
    "url": "https://esm.xsite.live/@xsite/[email protected]?target=es2022&external=react,react-dom,react/jsx-runtime,next,@xsite/common",
    "sri": "sha384-1jbc0tmbQEtIJeDdVbpIDuIG+yMJWD3sg5UAnjImYhq0BX4a+s8Iw+od9zdMGEbU"
  },
  "schema": {
    "path": "./json/schema.json",
    "url": "https://pub-e18ba885446f423f8922518b0660f7bd.r2.dev/@xsite/[email protected]/schema.json"
  },
  "puck": {
    "path": "./json/puck.json",
    "url": "https://pub-e18ba885446f423f8922518b0660f7bd.r2.dev/@xsite/[email protected]/puck.json"
  },
  "data": {
    "path": "./json/data.json",
    "url": "https://pub-e18ba885446f423f8922518b0660f7bd.r2.dev/@xsite/[email protected]/data.json"
  },
  "meta": {
    "path": "./json/meta.json",
    "url": "https://pub-e18ba885446f423f8922518b0660f7bd.r2.dev/@xsite/[email protected]/meta.json"
  },
  "preview": {
    "url": "https://xsite-components.s3.ap-south-1.amazonaws.com/accordion/accordion1.png"
  }
}

Overall Chain :

useEffect
  → fetchRuntimeCatalog()
  → GET /api/runtime-catalog
  → getCachedRuntimeCatalog()
  → buildRuntimeCatalog()
  → buildCatalogFromPackages()
  → loadPackageArtifacts() for every package
  → fetch descriptor.json
  → fetch data.json
  → fetch schema.json
  → fetch puck.json
  → fetch meta.json

Guide Remote Esm Component Loading Architecture