출처 : sergiodxa.com - Build a Master-Detail UI with React Router

✼✼ disclaimer ✼✼ 본 글은 AI 번역 후 직접 검수하여 작성했습니다. 효율적인 정보 전달을 위해 AI 번역을 활용하되, 부자연스러운 표현은 수정했습니다. 번역 오류가 있을 수 있으니 정확한 내용은 원문을 확인하시기 바랍니다.

react-router@7.0.0 사용

목록 탐색과 상세 보기를 동시에 제공하는 마스터-디테일 인터페이스(master-detail interface)는 많은 애플리케이션의 핵심 UI다. Linear의 이슈 트래커, Notion의 페이지 계층, 사이드바 목록이 달린 대시보드가 대표적인 사례다.

까다로운 부분은 URL을 직접 입력하거나 새로고침할 때도 자연스럽게 작동하게 만드는 것이다. /inbox/issue-123 같은 링크를 공유하면 제대로 열려야 하지만, 어떻게 접근했느냐에 따라 보여주는 방식을 달리해야 한다. 앱 내에서 이동할 땐 전체 레이아웃을 유지하고, 링크로 바로 들어왔을 땐 해당 내용만 집중해서 보여주는 식이다.

TL;DR: 이 튜토리얼의 작동 예제 레포가 여기 있다

라우트 구조 생성

핵심은 동일한 콘텐츠에 접근하는 두 가지 방법을 만드는 것이다. 탐색용(/inbox/:issue)과 직접 접근용(/:issue). 라우트 설정은 다음과 같다:

app/routes.ts
import { type RouteConfig, index, route } from "@react-router/dev/routes";

export default [
  index("routes/_index.tsx"),
  route("inbox", "routes/inbox.tsx", [
    index("routes/inbox-empty.tsx"),
    route(":issue", "routes/issue.tsx", { id: "routes/inbox/:issue" }),
  ]),
  route(":issue", "routes/issue.tsx", { id: "routes/:issue" }),
] satisfies RouteConfig;

이렇게 하면:

/는 /inbox로 리다이렉트
/inbox는 inbox 레이아웃에 빈 상태 표시
/inbox/:issue는 inbox 레이아웃 + issue 상세 표시
/:issue는 issue 상세만 표시

/inbox/:issue와 /:issue 모두 같은 라우트 모듈을 사용하지만 상황(context)에 따라 화면을 다르게 그린다.

레이아웃 상태 추적을 위한 컨텍스트 생성

issue 컴포넌트는 자신이 inbox 레이아웃 내부에 있는지 독립 실행 상태인지 알아야 한다. React Router 컨텍스트가 이 정보를 제공한다:

app/context/inbox.ts
import { createContext } from "react-router";

export const InboxContext = createContext<boolean>(false);

inbox 레이아웃 내부에서 렌더링될 땐 true, 디테일 뷰만 보여줄 땐 false가 된다.

inbox 레이아웃 구축

inbox 라우트 모듈이 마스터-디테일 레이아웃을 만들고 컨텍스트를 설정한다:

app/routes/inbox.tsx
import { InboxContext } from "~/context/inbox";
import type { Route } from "./+types/inbox";
import { issues } from "~/data";
import { href, NavLink, Outlet } from "react-router";

export const middleware: Route.MiddlewareFunction[] = [
  ({ context }) => {
    context.set(InboxContext, true);
  },
];

export async function loader() {
  return { issues: Array.from(issues.values()) };
}

export default function Component({ loaderData }: Route.ComponentProps) {
  return (
    <div className="flex divide-x divide-black dark:divide-white">
      <ol className="w-1/4 p-4">
        {loaderData.issues.map((issue) => (
          <li key={issue.id}>
            <NavLink to={href("/inbox/:issue", { issue: issue.id })}>
              {issue.title}
            </NavLink>
          </li>
        ))}
      </ol>
      <div className="w-3/4 p-4">
        <Outlet />
      </div>
    </div>
  );
}

미들웨어는 모든 중첩 라우트에서 실행되며 InboxContext를 true로 설정한다. 컴포넌트는 왼쪽에 issue 목록, 오른쪽에 상세 내용을 배치한 2열 레이아웃을 렌더링한다.

스마트 리다이렉트로 직접 접근 처리

issue 라우트 모듈은 두 컨텍스트 모두에서 작동하지만 직접 URL 접근을 처리하는 로직이 포함되어 있다:

app/routes/issue.tsx
import { InboxContext } from "~/context/inbox";
import type { Route } from "./+types/issue";
import { href, Link, redirect } from "react-router";
import { issues } from "~/data";

export async function loader({ request, params, context }: Route.LoaderArgs) {
  let isInbox = context.get(InboxContext);
  
  // inbox 내부이고 문서 요청이면 inbox이 아닌 버전의 issue로 리다이렉트
  if (isInbox && request.headers.get("Sec-Fetch-Dest") === "document") {
    return redirect(href("/:issue", params));
  }
  
  let issue = issues.get(params.issue);
  if (issue) return { issue, isInbox };
  throw new Error("Issue not found");
}

export default function Component({ loaderData }: Route.ComponentProps) {
  return (
    <div 
      className="relative data-[isinbox=false]:p-4" 
      data-isinbox={loaderData.isInbox}
    >
      {loaderData.isInbox ? (
        <Link 
          to={href("/inbox")} 
          className="text-blue-500 underline absolute top-0 right-0"
        >
          ⅹ Close
        </Link>
      ) : (
        <Link 
          to={href("/inbox")} 
          className="text-blue-500 underline absolute top-4 right-4"
        >
          ← Back to inbox
        </Link>
      )}
      <h1 className="text-2xl">
        {loaderData.issue.title} ({loaderData.issue.id})
      </h1>
      <p className="mt-4">{loaderData.issue.description}</p>
    </div>
  );
}

핵심은 리다이렉트 로직이다. 누군가 /inbox/1에 직접 접근하면(URL 입력이나 새로고침처럼) /1로 리다이렉트해서 디테일만 보여준다. 하지만 클라이언트 사이드 네비게이션은 inbox 컨텍스트에 머문다.

빈 상태와 루트 리다이렉트 추가

issue가 선택되지 않았을 때 보여줄 빈 상태를 만든다:

app/routes/inbox-empty.tsx
export default function Component() {
  return <h1>👈 Pick an issue</h1>;
}

그리고 루트를 inbox으로 리다이렉트한다:

app/routes/_index.tsx
import { href, redirect } from "react-router";

export async function loader() {
  return redirect(href("/inbox"));
}

리다이렉트 로직 이해하기

이 패턴의 핵심은 issue loader의 조건부 리다이렉트다:

if (isInbox && request.headers.get("Sec-Fetch-Dest") === "document") {
  return redirect(href("/:issue", params));
}

Sec-Fetch-Dest 헤더는 전체 페이지 요청(URL 입력, 새로고침, 외부 링크)인지 클라이언트 사이드 네비게이션인지 알려준다. 덕분에 동일한 URL이 사용자의 접근 방식에 따라 다르게 동작할 수 있다:

/inbox/1 직접 접근은 /1로 리다이렉트 (집중 뷰)
/inbox/1로의 링크 클릭은 /inbox/1에 머무름 (컨텍스트 보존)

왜 잘 작동하는가

이 패턴은 사용자 의도에 맞춰 적응한다:

탐색 중인 사용자는 컨텍스트가 있는 전체 인터페이스를 본다
직접 접근한 사용자는 산만함 없이 집중된 콘텐츠를 얻는다
URL은 여전히 공유 가능하고 북마크 가능하다

결과적으로 사용자가 앱을 탐색하든 외부 소스에서 특정 콘텐츠에 도달하든 작동하는 반응형 인터페이스가 완성된다.

[FE/react] React Router로 마스터-디테일 UI 만들기