빠른 시작

이 페이지는 흔한 React 데이터 컴포넌트를 utilinent의 선언적인 마크업으로 바꿉니다.

React 18 이상으로 만든 기존 애플리케이션에서 시작하세요. Utilinent는 앱을 만들거나 사용자 데이터를 가져오거나 로딩 상태를 소유하지 않습니다. 이 예시는 렌더링 분기만 교체합니다.

1. 설치

pnpm add @ilokesto/utilinent@1.2.0

react는 피어 의존성이므로 애플리케이션에 이미 설치되어 있어야 합니다. 컴포넌트는 패키지 루트에서, 훅은 ./hooks 하위 경로에서 가져옵니다.

import { For, Show } from '@ilokesto/utilinent';

2. 일반 React 코드에서 시작하기

type User = { id: string; name: string };

export function UserList({ users, loading }: { users?: User[]; loading: boolean }) {
  if (loading) return <p>Loading users...</p>;
  if (!users || users.length === 0) return <p>No users found.</p>;

  return (
    <ul>
      {users.map((user) => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

한 component에서는 괜찮습니다. 하지만 화면이 커질수록 loading, empty, list branch가 inline으로 반복되기 쉽습니다.

3. loading branch에 Show 사용하기

import { Show } from '@ilokesto/utilinent';

<Show when={!loading} fallback={<p>Loading users...</p>}>
  {/* loading이 false일 때의 content */}
</Show>

Show는 when이 truthy이면 children을, 아니면 fallback을 렌더링합니다.

4. array branch에 For 사용하기

import { For } from '@ilokesto/utilinent';

<For.ul each={users} fallback={<p>No users found.</p>}>
  {(user) => <li key={user.id}>{user.name}</li>}
</For.ul>

For.ul은 실제 <ul> 안에 list item을 렌더링합니다. wrapper element가 필요 없다면 tag 없는 For를 사용하세요.

5. 최종 component 조합하기

import { For, Show } from '@ilokesto/utilinent';

type User = { id: string; name: string };

export function UserList({ users, loading }: { users?: User[]; loading: boolean }) {
  return (
    <Show when={!loading} fallback={<p>Loading users...</p>}>
      <For.ul each={users} fallback={<p>No users found.</p>}>
        {(user) => <li key={user.id}>{user.name}</li>}
      </For.ul>
    </Show>
  );
}

<UserList loading users={undefined} />를 렌더링하면 Loading users...가 나타납니다. <UserList loading={false} users={[]} />로 바꾸면 No users found.가 나타나고, 사용자를 한 명 이상 넘기면 이름이 담긴 <ul>이 나타납니다.

6. 필요하면 완성된 예시 확장하기

아래 코드 조각은 위에서 완성한 컴포넌트의 반환값을 교체합니다. UserListSkeleton, EmptyUsers, UserRow는 애플리케이션에서 제공해야 하는 컴포넌트입니다.

<Show.section
  when={!loading}
  fallback={<UserListSkeleton />}
  aria-busy={loading}
>
  <For.ul each={users} fallback={<EmptyUsers />}> 
    {(user) => <UserRow key={user.id} user={user} />}
  </For.ul>
</Show.section>

Show.section, For.ul 같은 proxy tag는 DOM props와 ref를 underlying element에 전달합니다.

다음 단계

핵심 개념에서 mental model을 봅니다.
Show, For에서 정확한 동작을 확인합니다.
loading/error/success layout은 Async data guide를 보세요.

목차