improvement(settings): make settings section navigation feel instant

Every settings tab switch ran four sequential round-trips with no visual
feedback: a cold RSC request, then the panel render, then the section's
lazy chunk, then its queries. The heading was pushed up from the section
body, so the most static thing on the page arrived last and visibly
blanked between sections.

- resolve the section heading in the route layout from its navigation
  entry, so it paints with the shell instead of after the body's chunk
- add loading.tsx to all four settings planes, so a click commits the
  navigation immediately instead of holding the outgoing section
- give every code-split section a shared skeleton fallback, reused by the
  route boundary and the in-page Suspense boundary
- prefetch the route payload on sidebar hover/focus; the rows are buttons
  for the unsaved-changes guard, so they never got Next's <Link> prefetch
- scope the general-settings server prefetch to the three sections that
  read it, instead of blocking all 28 on it
- set staleTimes so returning to a tab reuses the client router cache
  rather than re-running the access gate
- warm workspace credentials under the type the secrets panel queries;
  the previous warm wrote a different cache entry and never landed

Author: waleedlatif1

apps/sim/app/account/settings/[section]/loading.tsx

@@ -0,0 +1,13 @@
+import { SettingsSectionSkeleton } from '@/components/settings/settings-section-skeleton'
+
+/**
+ * Route-transition fallback for every account settings section.
+ *
+ * Without a loading boundary the App Router holds the outgoing section on screen until the
+ * incoming page's access gate resolves, so a click reads as a dead click. This commits the
+ * navigation immediately — the shell's heading updates with it — and lets the gate resolve
+ * behind the placeholder.
+ */
+export default function AccountSettingsSectionLoading() {
+  return <SettingsSectionSkeleton />
+}

apps/sim/app/account/settings/[section]/page.tsx

@@ -9,6 +9,7 @@ import {
   getSettingsSectionMeta,
   parseSettingsPathSection,
 } from '@/components/settings/navigation'
+import { SettingsSectionSkeleton } from '@/components/settings/settings-section-skeleton'
 import { getSession } from '@/lib/auth'
 import { isBillingEnabled } from '@/lib/core/config/env-flags'
 import { isPlatformAdmin } from '@/lib/permissions/super-user'
@@ -53,12 +54,12 @@ export default async function AccountSettingsSectionPage({
 
   /**
    * Sections read URL query params via nuqs (which uses `useSearchParams`
-   * internally), so the renderer must sit under a Suspense boundary. The
-   * `null` fallback matches the existing visual behavior — the sections are
-   * `next/dynamic` components that render nothing while their chunk loads.
+   * internally), so the renderer must sit under a Suspense boundary. It shares the
+   * route's loading placeholder, so a section resolving its params looks the same as one
+   * whose chunk is still in flight.
    */
   return (
-    <Suspense fallback={null}>
+    <Suspense fallback={<SettingsSectionSkeleton />}>
       <AccountSettingsRenderer section={parsed} />
     </Suspense>
   )

apps/sim/app/organization/[organizationId]/settings/[section]/loading.tsx

@@ -0,0 +1,13 @@
+import { SettingsSectionSkeleton } from '@/components/settings/settings-section-skeleton'
+
+/**
+ * Route-transition fallback for every organization settings section.
+ *
+ * Without a loading boundary the App Router holds the outgoing section on screen until the
+ * incoming page's access gate resolves, so a click reads as a dead click. This commits the
+ * navigation immediately — the shell's heading updates with it — and lets the gate resolve
+ * behind the placeholder.
+ */
+export default function OrganizationSettingsSectionLoading() {
+  return <SettingsSectionSkeleton />
+}

apps/sim/app/selfhost/settings/[section]/loading.tsx

@@ -0,0 +1,13 @@
+import { SettingsSectionSkeleton } from '@/components/settings/settings-section-skeleton'
+
+/**
+ * Route-transition fallback for every self-hosted settings section.
+ *
+ * Without a loading boundary the App Router holds the outgoing section on screen until the
+ * incoming page's access gate resolves, so a click reads as a dead click. This commits the
+ * navigation immediately — the shell's heading updates with it — and lets the gate resolve
+ * behind the placeholder.
+ */
+export default function SelfHostSettingsSectionLoading() {
+  return <SettingsSectionSkeleton />
+}

apps/sim/app/selfhost/settings/[section]/page.tsx

@@ -8,6 +8,7 @@ import {
   SELFHOST_SETTINGS_ITEMS,
 } from '@/components/settings/navigation'
 import { SelfHostSettingsRenderer } from '@/components/settings/selfhost-settings-renderer'
+import { SettingsSectionSkeleton } from '@/components/settings/settings-section-skeleton'
 import { getSession } from '@/lib/auth'
 import { isBillingEnabled, isHosted } from '@/lib/core/config/env-flags'
 
@@ -46,10 +47,12 @@ export default async function SelfHostSettingsSectionPage({
 
   /**
    * Sections read URL query params via nuqs (which uses `useSearchParams`
-   * internally), so the renderer must sit under a Suspense boundary.
+   * internally), so the renderer must sit under a Suspense boundary. It shares the
+   * route's loading placeholder, so a section resolving its params looks the same as one
+   * whose chunk is still in flight.
    */
   return (
-    <Suspense fallback={null}>
+    <Suspense fallback={<SettingsSectionSkeleton />}>
       <SelfHostSettingsRenderer section={parsed} />
     </Suspense>
   )

apps/sim/app/workspace/[workspaceId]/settings/[section]/layout.tsx

@@ -2,17 +2,31 @@ import {
   SettingsHeaderProvider,
   SettingsHeaderShell,
 } from '@/app/workspace/[workspaceId]/settings/components/settings-header/settings-header'
+import { resolveSettingsSection } from '@/app/workspace/[workspaceId]/settings/navigation'
 
 /**
  * Persistent chrome for the settings panel pages. The header bar, title,
  * description, scroll region, and centered column live in the shell and stay
  * mounted across section navigation — only the body swaps. Scoped to `[section]`
  * so detail routes (e.g. `secrets/[credentialId]`) keep their own chrome.
+ *
+ * The heading is resolved here rather than pushed up from the section body, so it
+ * paints with the shell instead of waiting on the body's lazily-loaded chunk. An
+ * unknown segment resolves to `null` and the page below it calls `notFound()`.
  */
-export default function SettingsSectionLayout({ children }: { children: React.ReactNode }) {
+export default async function SettingsSectionLayout({
+  children,
+  params,
+}: {
+  children: React.ReactNode
+  params: Promise<{ section: string }>
+}) {
+  const { section } = await params
+  const meta = resolveSettingsSection(section)?.meta ?? null
+
   return (
     <SettingsHeaderProvider>
-      <SettingsHeaderShell>{children}</SettingsHeaderShell>
+      <SettingsHeaderShell meta={meta}>{children}</SettingsHeaderShell>
     </SettingsHeaderProvider>
   )
 }

apps/sim/app/workspace/[workspaceId]/settings/[section]/loading.tsx

@@ -0,0 +1,12 @@
+import { SettingsSectionSkeleton } from '@/components/settings/settings-section-skeleton'
+
+/**
+ * Route-transition fallback for every settings section.
+ *
+ * Without a loading boundary the App Router holds the outgoing section on screen until the
+ * incoming page's access gate resolves, so a click reads as a dead click. This commits the
+ * navigation immediately and lets the gate resolve behind it.
+ */
+export default function SettingsSectionLoading() {
+  return <SettingsSectionSkeleton />
+}

apps/sim/app/workspace/[workspaceId]/settings/[section]/page.test.tsx

@@ -87,8 +87,16 @@ vi.mock('@/app/_shell/providers/get-query-client', () => ({
   getQueryClient: vi.fn(),
 }))
 
+const { mockSections } = vi.hoisted(() => ({
+  mockSections: ['general', 'billing', 'secrets', 'sessions'],
+}))
+
 vi.mock('@/app/workspace/[workspaceId]/settings/navigation', () => ({
-  allNavigationItems: [{ id: 'general' }, { id: 'billing' }, { id: 'secrets' }, { id: 'sessions' }],
+  allNavigationItems: mockSections.map((id) => ({ id })),
+  resolveSettingsSection: vi.fn((section: string) => {
+    const id = section === 'subscription' ? 'billing' : section
+    return mockSections.includes(id) ? { id, meta: { title: id } } : null
+  }),
   getSettingsSectionMeta: vi.fn(() => null),
 }))
 

apps/sim/app/workspace/[workspaceId]/settings/[section]/page.tsx

@@ -9,6 +9,7 @@ import {
   resolveWorkspaceNavigation,
   type WorkspaceSettingsSection,
 } from '@/components/settings/navigation'
+import { SettingsSectionSkeleton } from '@/components/settings/settings-section-skeleton'
 import { getSession } from '@/lib/auth'
 import { isOrganizationOnEnterprisePlan } from '@/lib/billing'
 import { hasWorkspaceInboxAccess, hasWorkspaceSandboxAccess } from '@/lib/billing/core/subscription'
@@ -20,8 +21,7 @@ import { isPlatformAdmin } from '@/lib/permissions/super-user'
 import { getWorkspaceHostContextForViewer } from '@/lib/workspaces/host-context'
 import { getQueryClient } from '@/app/_shell/providers/get-query-client'
 import {
-  allNavigationItems,
-  getSettingsSectionMeta,
+  resolveSettingsSection,
   type SettingsSection,
 } from '@/app/workspace/[workspaceId]/settings/navigation'
 import { resolveWorkspaceGroup } from '@/ee/access-control/utils/permission-check'
@@ -33,14 +33,6 @@ interface WorkspaceSettingsSectionPageProps {
   params: Promise<{ workspaceId: string; section: string }>
 }
 
-const SECTION_ALIASES: Readonly<Record<string, SettingsSection>> = {
-  subscription: 'billing',
-  team: 'organization',
-  'api-keys': 'apikeys',
-  // Verified domains moved into the SSO page; keep old links working.
-  domains: 'sso',
-}
-
 const TOP_LEVEL_REDIRECTS: Readonly<Record<string, (workspaceId: string) => string>> = {
   integrations: (workspaceId) => `/workspace/${workspaceId}/integrations`,
   skills: (workspaceId) => `/workspace/${workspaceId}/skills`,
@@ -77,12 +69,19 @@ const ORGANIZATION_SECTION_MAP: Partial<Record<SettingsSection, OrganizationSett
   whitelabeling: 'whitelabeling',
 }
 
-function parseSection(section: string): SettingsSection | null {
-  const normalized = SECTION_ALIASES[section] ?? section
-  return allNavigationItems.some((item) => item.id === normalized)
-    ? (normalized as SettingsSection)
-    : null
-}
+/**
+ * Sections whose first paint reads the general-settings query.
+ *
+ * Their bodies default a missing value (`?? true` / `?? false`) and drive a switch off it, so
+ * without a hydrated entry they paint the fallback and visibly flip when the client fetch
+ * lands. The workspace layout's `SettingsLoader` warms this key only after hydration, which
+ * covers client navigation but not a direct load of one of these sections.
+ */
+const GENERAL_SETTINGS_SECTIONS: ReadonlySet<SettingsSection> = new Set([
+  'general',
+  'billing',
+  'admin',
+])
 
 /**
  * Settings availability varies across workspaces, so a preserved section may
@@ -96,9 +95,7 @@ export async function generateMetadata({
   params,
 }: WorkspaceSettingsSectionPageProps): Promise<Metadata> {
   const { section } = await params
-  const parsed = parseSection(section)
-  const meta = parsed ? getSettingsSectionMeta(parsed) : null
-  return { title: meta?.label ?? 'Settings' }
+  return { title: resolveSettingsSection(section)?.meta.title ?? 'Settings' }
 }
 
 export default async function WorkspaceSettingsSectionPage({
@@ -110,8 +107,9 @@ export default async function WorkspaceSettingsSectionPage({
   const { workspaceId, section } = await params
   const topLevelHref = TOP_LEVEL_REDIRECTS[section]?.(workspaceId)
   if (topLevelHref) redirect(topLevelHref)
-  const parsed = parseSection(section)
-  if (!parsed) notFound()
+  const resolved = resolveSettingsSection(section)
+  if (!resolved) notFound()
+  const parsed = resolved.id
 
   const hostContext = await getWorkspaceHostContextForViewer(workspaceId, session.user.id)
   if (!hostContext) notFound()
@@ -191,16 +189,25 @@ export default async function WorkspaceSettingsSectionPage({
 
   const queryClient = getQueryClient()
   /**
-   * Awaited, not fired and forgotten: only a settled query is dehydrated, so an unawaited
-   * prefetch is dropped from the payload and the panel waterfalls anyway. The viewer's
-   * profile is already seeded by the workspace layout under the same key, so it is not
-   * repeated here.
+   * Scoped to the sections that actually read the key. The prefetch has to be awaited — an
+   * unsettled query is dropped from the dehydrated payload, so firing and forgetting would
+   * waterfall anyway — which means running it unconditionally charged the other ~25 sections
+   * a blocking round-trip for a cache entry they never touch. The viewer's profile is seeded
+   * by the workspace layout under a different key and is not repeated here.
    */
-  await prefetchGeneralSettings(queryClient)
+  if (GENERAL_SETTINGS_SECTIONS.has(parsed)) {
+    await prefetchGeneralSettings(queryClient)
+  }
 
   return (
     <HydrationBoundary state={dehydrate(queryClient)}>
-      <Suspense fallback={null}>
+      {/*
+        Sections read URL query params via nuqs (which uses `useSearchParams` internally),
+        so the panel must sit under a Suspense boundary. It shares the route's loading
+        placeholder, so a section resolving its params looks the same as one whose chunk is
+        still in flight.
+      */}
+      <Suspense fallback={<SettingsSectionSkeleton />}>
         <SettingsPage section={parsed} />
       </Suspense>
     </HydrationBoundary>