Code Splitting

Catalyst 0.3.x+

Use split() from catalyst-core for Vite-aware code splitting that works with Catalyst SSR and client hydration.

import { split } from "catalyst-core"
import HomeFallback from "@Fallback/HomeFallback/HomeFallback.js"

const Home = split(() => import("@pages/Home/Home.js"), {
    ssr: true,
    fallback: <HomeFallback />,
})

const Chart = split(() => import("@components/Chart/Chart.js"), {
    ssr: false,
    fallback: <div>Loading chart...</div>,
})

The client entry must wait for split modules used by SSR before hydrating:

import { RouterProvider, hydrationReady } from "catalyst-core"
import { hydrateRoot } from "react-dom/client"

window.addEventListener("load", () => {
    hydrationReady().then(() => {
        hydrateRoot(document.getElementById("app"), <RouterProvider router={router} />)
    })
})

Options

Option	Type	Description
`ssr`	boolean	Render on the server. Defaults to `true`.
`fallback`	ReactNode	Content rendered while the split module loads.
`rootOptions`	object	Intersection observer options for visibility-based loading.
`onVisible`	function	Called when a visibility-loaded split component becomes visible.

Route components keep their serverFetcher, clientFetcher, and setMetaData statics when wrapped with split().

Legacy Catalyst 0.2.x

Catalyst 0.2.x uses @loadable/component and loadableReady(). Keep that implementation while the application remains on 0.2.x; replace it with split() and hydrationReady() as part of the 0.3.x migration. Do not install @loadable/component in a 0.3.x application.

Best Practices

Split route-level components before small leaf components.
Keep SSR enabled for above-the-fold and SEO-critical content.
Use ssr: false for browser-only components and provide a hydration-stable fallback.
Use meaningful loading skeletons that match the final component dimensions.