어드민 UI에 페이지 헤더 공통 컴포넌트 도입

어드민 UI 전반에 PageHeader 컴포넌트를 만들어서 붙이는 작업을 했다. 커밋 하나짜리 작업이지만, 팀 입장에서는 꽤 의미 있는 시발점이었다.

왜 이 타이밍에

어드민 페이지가 늘어나면서 슬슬 문제가 보이기 시작했다. 각 페이지마다 타이틀 영역을 제각각 구현해놓은 것이다. 누군가는 <h1> 하나 달랑, 누군가는 설명 텍스트까지, 또 누군가는 상단 액션 버튼까지 거기다 끼워놓은 상태. 디자인 일관성도 없고, 새 페이지 만들 때마다 "위 페이지 참고해서 복붙하면 되죠?" 식으로 흘러가는 패턴이 반복됐다.

이런 상황에서 컴포넌트 하나 만드는 게 "개발자가 알아서 하는 리팩터링" 수준으로 보일 수도 있다. 근데 팀장 입장에서 이건 명확히 공통화 기준을 세우는 작업이라서, 그냥 조용히 올리기보다 코드리뷰 때 배경을 같이 설명했다.

"앞으로 어드민 페이지 추가할 때 PageHeader는 기본으로 쓰는 거예요. 타이틀/설명/액션 버튼은 여기서 통일합니다."

이 한마디가 없으면 컴포넌트 만들어봤자 다음 사람이 또 <h1> 직접 쓴다.

변경된 파일들과 역할

이번에 PageHeader를 적용한 페이지는 총 6개다.

성격이 다 다른 페이지들이라서 일부러 이쪽부터 적용했다. 목록형, 설정형, 로그형 등 케이스가 섞여 있으면 PageHeader가 얼마나 유연하게 버텨주는지 바로 확인할 수 있거든. 만약 비슷한 페이지만 골라서 적용했다가 나중에 예외 케이스 터지면 그게 더 골치아프다.

컴포넌트 구조

PageHeader는 단순하게 잡았다. 과하게 추상화하면 나중에 오히려 손대기 불편해진다.

interface PageHeaderProps {
  title: string;
  description?: string;
  actions?: React.ReactNode;
}

export function PageHeader({ title, description, actions }: PageHeaderProps) {
  return (
    <div className="flex items-start justify-between mb-6">
      <div>
        <h1 className="text-2xl font-semibold">{title}</h1>
        {description && (
          <p className="text-sm text-muted-foreground mt-1">{description}</p>
        )}
      </div>
      {actions && <div className="flex gap-2">{actions}</div>}
    </div>
  );
}

actions를 React.ReactNode로 열어둔 게 포인트다. 버튼 하나일 수도 있고, 드롭다운 + 버튼 조합일 수도 있으니까. 이 부분을 buttonLabel?: string 같은 식으로 닫아버리면 결국 얼마 안 가서 props 추가 요청이 들어온다. 처음부터 슬롯으로 열어두는 게 낫다.

사용 측에서는 이렇게 쓴다.

// audit-log/page.tsx
<PageHeader
  title="Audit Log"
  description="운영자 활동 내역을 확인합니다."
/>

// ad-units/page.tsx
<PageHeader
  title="Ad Units"
  actions={<Button size="sm">새 광고 단위 추가</Button>}
/>

이 작업의 진짜 의미

PageHeader 하나 만드는 게 기술적으로 어려운 일은 아니다. 근데 이게 팀에서 작동하려면 두 가지가 필요하다.

• 적용 예시가 충분해야 한다: "어디서 어떻게 쓰는지" 레퍼런스가 없으면 새 페이지 개발할 때 또 망설이게 된다. 그래서 이번에 6개 페이지에 한 번에 적용한 거다. 보면 바로 따라 쓸 수 있도록.
• 컨벤션이 명시되어야 한다: 코드만 있고 말이 없으면 "몰랐어요"가 된다. 리뷰 코멘트든 위키든 어딘가에 "어드민 페이지는 PageHeader 기본 사용"이 적혀 있어야 한다.

공통 컴포넌트는 만드는 것보다 팀 안에서 자리잡히는 게 더 어렵다. 이 작업은 그 첫 번째 스텝이었다.

끝.

🛒 이 글과 어울리는 추천 상품

• 기계식키보드 쿠팡에서 보기 →
• 모니터암 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.