Next.js URL Split Screen

v1.0.0

Next.js App Router에서 URL만 지정해 해당 page.tsx를 서버에서 렌더링하고 FlexLayoutSplitScreen의 새 pane으로 드롭합니다.

동작 흐름

일반 FlexLayout은 기존처럼 레이아웃과 리사이즈를 담당하고, 동적 분할은 FlexLayoutSplitScreen이 담당합니다. Next.js 전용 진입점은 DragBox의 url을 생성된 registry로 해석해 서버에서 page.tsx를 렌더링한 뒤 그 결과를 해당 split pane에 전달합니다.

text

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

1. Registry 생성

사용 프로젝트의 스크립트 상단에 앱 경로와 출력 경로만 설정합니다. 생성 결과는 route group과 동적 segment를 해석할 수 있는 정적 import registry이며, 기본 export는 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. FlexLayoutNextSplitScreen 적용

FlexLayoutNextSplitScreen 은 생성된 page registry를 이용해 URL pane의 서버 렌더링을 제공하는 Next.js 전용 wrapper입니다. URL 기반 pane을 받을 FlexLayoutSplitScreen 트리를 한 번 감싸면 됩니다.

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. URL pane 새로고침 복원

복원 대상은 다시 만들 수 있는 Next URL pane만입니다.

FlexLayoutNextSplitScreen으로 감싸져 있고, Next.js 전용 DragBox가 url 방식이며, targetComponent를 직접 지정하지 않고 iframe도 사용하지 않는 pane만 persistent snapshot에 포함됩니다. targetComponent 방식은 평소 렌더링을 막지 않지만 새로고침 복원 대상에서는 제외됩니다.

persistence를 지정하면 ReactElement 자체가 아니라 URL, screenKey, containerName, navigationTitle, 분할 구조처럼 직렬화 가능한 metadata만 storage에 저장합니다. restoreOnReload가 false면 persistence를 사용하지 않고, syncWithBrowserUrl이 true면 pathname + search URL별 snapshot을 저장합니다. 뒤로가기/앞으로가기 또는 같은 URL 재방문 시 해당 URL의 전체 URL 기반 분할 상태를 복원하고, 새로고침 시에도 현재 URL snapshot을 복원합니다.

tsx

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

4. DragBox에는 URL만 전달

Next.js 전용 DragBox는 targetComponent를 직접 만들 필요 없이 url만 받습니다. targetComponent를 명시하면 기존 방식이 우선하며 해당 pane은 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은 선택 사항

iframe의 기본값은 false입니다. 외부 URL이나 독립 문서 컨텍스트가 필요한 경우에만 iframe을 true로 지정합니다. iframe 모드는 FlexLayoutNextSplitScreen의 page registry가 필요하지 않으며 persistence 대상에서도 제외됩니다.

tsx

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

라우터 컨텍스트 제약

서버 page에는 URL에서 추출한 params와 searchParams가 전달됩니다. 다만 split pane은 별도의 Next Router가 아니므로 내부 Client Component의 usePathname, useParams, useSearchParams는 브라우저의 실제 URL을 기준으로 동작합니다.