Next.js URL Split Screen

v1.0.0

In Next.js App Router, provide only a URL to server-render the matching page.tsx and drop it into a new FlexLayoutSplitScreen pane.

How it works

Regular FlexLayout keeps handling layout and resizing, while FlexLayoutSplitScreen handles dynamic splitting. The Next.js entry resolves the DragBox url through the generated registry, renders the matching page.tsx on the server, and delivers the result to that split pane.

text

FlexLayoutSplitScreenDragBox url
  -> generated page registry
  -> FlexLayoutNextSplitScreen
  -> Server Component page.tsx
  -> RSC result
  -> FlexLayoutSplitScreen pane

1. Generate the registry

Set only the app path and output path at the top of the script of the used project. The generated result is a static import registry that can interpret route groups and dynamic segments, with the default export being FlexLayoutNextSplitScreen.

scripts/generateFlexLayoutSplitScreenPageRegistry.mjs

import { generateFlexLayoutSplitScreenPageRegistry } from "@byeolnaerim/flex-layout/next/generator";

const registryConfigs = [
  {
    appDir: "src/app",
    outFile: "src/generated/flexLayoutPageRegistry.ts",
    excludedRoutes: [],
    includeLayouts: true,
    excludeRootLayout: true,
  },
];

registryConfigs.forEach((config) => {
  generateFlexLayoutSplitScreenPageRegistry(config);
});

2. Apply FlexLayoutNextSplitScreen

FlexLayoutNextSplitScreen is a Next.js specific wrapper that provides server rendering for the URL pane using the generated page registry. It only needs to wrap the FlexLayoutSplitScreen tree that receives URL-based panes once.

tsx

import FlexLayoutNextSplitScreen from "@/generated/flexLayoutPageRegistry";
import { FlexLayoutSplitScreen } from "@byeolnaerim/flex-layout";

<FlexLayoutNextSplitScreen
  persistence={{
    storage: "auto",
	keyName:"byeolnaerim-docs-split-screen-v6",
    restoreOnReload: true,
    syncWithBrowserUrl: true,
  }}
>
  <FlexLayoutSplitScreen
    layoutName="root-split-screen"
    containerName="main-split-screen"
    navigationTitle="ROOT"
	dropDocumentOutsideOption={{
		openUrl:
			localizePathname(
				"/",
				locale,
			),
		widthRatio: 0.7,
		heightRatio: 0.5,
	}}
  >
    {children}
  </FlexLayoutSplitScreen>
</FlexLayoutNextSplitScreen>

3. Restore URL pane refresh

The restoration target is only the Next URL pane that can be recreated.

Only includes panes wrapped in FlexLayoutNextSplitScreen, with Next.js specific DragBox that uses URL method, and does not directly specify targetComponent or use iframes in persistent snapshots. The targetComponent method does not block normal rendering but is excluded from the refresh restoration target.

When persistence is specified, only serializable metadata like URL, screenKey, containerName, navigationTitle, and split structure is stored, not the ReactElement itself. If restoreOnReload is false, persistence is not used, and if syncWithBrowserUrl is true, a snapshot is saved for each pathname + search URL. The full URL-based split state for that URL is restored when navigating back/forward or revisiting the same URL, and the current URL snapshot is restored on refresh.

tsx

<FlexLayoutNextSplitScreen
  persistence={{
    storage: "auto",
    keyName: "workspace-split-screen",
    restoreOnReload: true,
    syncWithBrowserUrl: false,
  }}
>
  {children}
</FlexLayoutNextSplitScreen>

4. Only the URL is passed to DragBox.

The Next.js specific DragBox only receives the URL without needing to create a targetComponent. If a targetComponent is specified, the existing method takes precedence, and that pane is excluded from persistence.

tsx

import { FlexLayoutSplitScreenDragBox } from "@byeolnaerim/flex-layout/next";

<FlexLayoutSplitScreenDragBox
  url="/flex-layout/guides/next-url-split-screen"
  containerName="next-url-split-screen"
  navigationTitle="Next.js URL Split Screen"
>
  <button type="button">Drag me</button>
</FlexLayoutSplitScreenDragBox>

5. iframe is optional.

The default for iframe is false. Set iframe to true only if an external URL or independent document context is needed. The iframe mode does not require a page registry for FlexLayoutNextSplitScreen and is also excluded from persistence.

tsx

<FlexLayoutSplitScreenDragBox
  url="https://example.com"
  iframe
  containerName="external-page"
  navigationTitle="External page"
>
  <button type="button">External page</button>
</FlexLayoutSplitScreenDragBox>

Router context limitations

The server page receives params and searchParams extracted from the URL. However, a split pane is not an independent Next Router, so usePathname, useParams, and useSearchParams inside Client Components still resolve against the browser's real URL.