raystack · rsbh · May 18, 2026 · May 18, 2026 · May 18, 2026 · May 18, 2026
diff --git a/packages/chronicle/src/server/App.module.css b/packages/chronicle/src/server/App.module.css
@@ -0,0 +1,4 @@
+.fallback {
+  padding: var(--rs-space-8);
+  width: 80%;
+}
diff --git a/packages/chronicle/src/server/App.tsx b/packages/chronicle/src/server/App.tsx
@@ -1,17 +1,20 @@
 import '@raystack/apsara/normalize.css';
 import '@raystack/apsara/style.css';
-import { ThemeProvider } from '@raystack/apsara';
+import { ThemeProvider, Skeleton, Flex } from '@raystack/apsara';
+import { lazy, Suspense } from 'react';
 import { Navigate, useLocation } from 'react-router';
 import { Head } from '@/lib/head';
 import { usePageContext } from '@/lib/page-context';
 import { resolveRoute, RouteType } from '@/lib/route-resolver';
-import { ApiLayout } from '@/pages/ApiLayout';
-import { ApiPage } from '@/pages/ApiPage';
-import { DocsLayout } from '@/pages/DocsLayout';
-import { DocsPage } from '@/pages/DocsPage';
-import { LandingPage } from '@/pages/LandingPage';
 import type { ChronicleConfig } from '@/types';
 import { getThemeConfig } from '@/themes/registry';
+import styles from './App.module.css';
+
+const ApiLayout = lazy(() => import('@/pages/ApiLayout').then(m => ({ default: m.ApiLayout })));
+const ApiPage = lazy(() => import('@/pages/ApiPage').then(m => ({ default: m.ApiPage })));
+const DocsLayout = lazy(() => import('@/pages/DocsLayout').then(m => ({ default: m.DocsLayout })));
+const DocsPage = lazy(() => import('@/pages/DocsPage').then(m => ({ default: m.DocsPage })));
+const LandingPage = lazy(() => import('@/pages/LandingPage').then(m => ({ default: m.LandingPage })));
 
 export function App() {
   const { pathname } = useLocation();
@@ -35,19 +38,33 @@ export function App() {
       forcedTheme={themeConfig.forcedTheme}
     >
       <RootHead config={config} />
-      {isApi ? (
-        <ApiLayout>
-          <ApiPage slug={apiSlug} />
-        </ApiLayout>
-      ) : (
-        <DocsLayout hideSidebar={isLanding}>
-          {isLanding ? <LandingPage /> : <DocsPage slug={docsSlug} />}
-        </DocsLayout>
-      )}
+      <Suspense fallback={<PageFallback />}>
+        {isApi ? (
+          <ApiLayout>
+            <ApiPage slug={apiSlug} />
+          </ApiLayout>
+        ) : (
+          <DocsLayout hideSidebar={isLanding}>
+            {isLanding ? <LandingPage /> : <DocsPage slug={docsSlug} />}
+          </DocsLayout>
+        )}
+      </Suspense>
     </ThemeProvider>
   );
 }
 
+function PageFallback() {
+  return (
+    <Flex direction="column" gap={4} className={styles.fallback}>
+      <Skeleton width="40%" height="var(--rs-line-height-t2)" />
+      <Skeleton width="60%" height="var(--rs-line-height-regular)" />
+      {[...new Array(12)].map((_, i) => (
+        <Skeleton key={i} width="100%" height="var(--rs-line-height-regular)" />
+      ))}
+    </Flex>
+  );
+}
+
 function RootHead({ config }: { config: ChronicleConfig }) {
   return (
     <Head

diff --git a/packages/chronicle/src/themes/default/Layout.tsx b/packages/chronicle/src/themes/default/Layout.tsx
@@ -9,12 +9,13 @@ import {
 import { Flex, IconButton, Button, Sidebar } from '@raystack/apsara';
 import { PlayIcon } from '@radix-ui/react-icons';
 import { cx } from 'class-variance-authority';
-import { useState, useEffect, useMemo, useRef } from 'react';
+import { useState, useEffect, useMemo, useRef, lazy, Suspense } from 'react';
 import { Link as RouterLink, useLocation, useNavigate } from 'react-router';
 import type { OpenAPIV3 } from 'openapi-types';
 import { MethodBadge } from '@/components/api/method-badge';
 import { useApiOperation } from '@/lib/use-api-operation';
-import { PlaygroundDialog } from '@/components/api/playground-dialog';
+
+const PlaygroundDialog = lazy(() => import('@/components/api/playground-dialog').then(m => ({ default: m.PlaygroundDialog })));
 import { ClientThemeSwitcher } from '@/components/ui/client-theme-switcher';
 import { Search } from '@/components/ui/search';
 import { Breadcrumbs } from '@/components/ui/breadcrumbs';
@@ -144,7 +145,7 @@ export function Layout({
                   ))}
                   {apiEntries.map(api => (
                     <Sidebar.Item
-                      key={api.basePath}
+                      key={`${api.basePath}-${api.name}`}
                       href={api.basePath}
                       active={isApiBase(api.basePath)}
                       leadingIcon={renderConfigIcon(
@@ -371,18 +372,22 @@ function TestRequestButton() {
       >
         Test request
       </Button>
-      <PlaygroundDialog
-        key={`${match.spec.name}-${match.path}-${match.method}`}
-        open={open}
-        onOpenChange={setOpen}
-        method={match.method}
-        path={match.path}
-        operation={match.operation}
-        serverUrl={match.spec.server.url}
-        specName={match.spec.name}
-        auth={match.spec.auth}
-        document={match.spec.document}
-      />
+      {open && (
+        <Suspense fallback={null}>
+          <PlaygroundDialog
+            key={`${match.spec.name}-${match.path}-${match.method}`}
+            open={open}
+            onOpenChange={setOpen}
+            method={match.method}
+            path={match.path}
+            operation={match.operation}
+            serverUrl={match.spec.server.url}
+            specName={match.spec.name}
+            auth={match.spec.auth}
+            document={match.spec.document}
+          />
+        </Suspense>
+      )}
     </>
   );
 }

diff --git a/packages/chronicle/src/themes/default/Page.tsx b/packages/chronicle/src/themes/default/Page.tsx
@@ -1,9 +1,11 @@
 'use client';
 
 import { Flex, Headline } from '@raystack/apsara';
+import { lazy, Suspense } from 'react';
 import type { ThemePageProps } from '@/types';
 import styles from './Page.module.css';
-import { Toc } from './Toc';
+
+const Toc = lazy(() => import('./Toc').then(m => ({ default: m.Toc })));
 
 export function Page({ page }: ThemePageProps) {
   return (
@@ -16,7 +18,9 @@ export function Page({ page }: ThemePageProps) {
         )}
         <div className={styles.content}>{page.content}</div>
       </article>
-      <Toc items={page.toc} />
+      <Suspense fallback={null}>
+        <Toc items={page.toc} />
+      </Suspense>
     </Flex>
   );
 }