JSX 컴포넌트

JSX는 무엇인가요?

JSX는 채팅 답변 안에 넣을 수 있는 작은 화면 조각입니다.

일반 채팅은 대부분 글로 진행됩니다. 그런데 어떤 작품은 글만으로는 부족합니다.

• 미연시 선택지 버튼
• 캐릭터 프로필 카드
• 퀘스트 진행 카드
• 인스타그램 게시물처럼 보이는 출력
• 일기장, 영수증, 스마트폰 알림 같은 고정된 양식

이런 것을 매번 AI가 글로 흉내 내게 하면 모양이 자주 깨집니다. JSX 컴포넌트를 만들어두면, AI는 필요한 값만 채우고 NoahChat이 정해진 모양으로 보여줍니다.

상태창과 JSX는 어떻게 다른가요?

상태창과 JSX는 둘 다 화면에 보이는 UI를 만들 수 있지만 용도가 다릅니다.

간단히 말하면, 계속 유지되는 상태판은 상태창, 특정 순간에 등장하는 예쁜 출력물은 JSX라고 생각하면 됩니다.

언제 JSX를 쓰면 좋나요?

아래 질문 중 하나라도 "예"라면 JSX를 고려해보세요.

• 독자가 버튼을 눌러 선택지를 보내게 하고 싶나요?
• 매번 같은 모양의 카드를 출력해야 하나요?
• AI가 텍스트로 표나 카드 모양을 만들다가 자주 깨지나요?
• 작품의 분위기를 살리는 특별한 화면이 필요한가요?
• 상태창이 아니라, 답변 중간에 한 번씩 등장하는 UI가 필요한가요?

반대로 아래처럼 단순한 작품이라면 굳이 JSX를 만들지 않아도 됩니다.

• 캐릭터와 자연스럽게 대화하는 것이 핵심인 작품
• 글 서사와 대사만으로 충분한 작품
• 화면보다 말투와 상황 몰입이 중요한 작품

JSX 컴포넌트의 구성

JSX 컴포넌트는 네 가지를 입력해서 만듭니다.

Props가 뭔가요?

Props는 컴포넌트에 들어가는 빈칸이라고 생각하면 됩니다.

예를 들어 퀘스트 카드에는 매번 제목과 보상이 달라질 수 있습니다.

퀘스트 카드
- 제목: 잃어버린 열쇠 찾기
- 설명: 도서관에서 사라진 은색 열쇠를 찾아야 합니다.
- 보상: 신뢰도 +5

여기서 제목, 설명, 보상이 props입니다. 컴포넌트 모양은 그대로 두고, props 값만 장면마다 바뀝니다.

가장 쉬운 시작 방법

처음부터 코드를 직접 쓰기보다 템플릿을 먼저 사용해보세요.

1. 스튜디오에서 컴포넌트 탭을 엽니다.
2. 템플릿 라이브러리를 펼칩니다.
3. 작품에 어울리는 템플릿을 선택합니다.
4. 활성화합니다.
5. 활용 지침을 작품에 맞게 수정합니다.
6. 채팅 해보기에서 AI가 적절한 장면에 컴포넌트를 쓰는지 확인합니다.

템플릿으로 충분하면 코드를 만질 필요가 없습니다.

직접 만들 때 입력 예시

1. 컴포넌트 이름

영문으로 시작하고, 영문/숫자/밑줄만 사용할 수 있습니다.

QuestCard

좋은 이름은 AI가 용도를 추측하기 쉽습니다.

2. 활용 지침

활용 지침은 짧고 분명해야 합니다.

퀘스트가 새로 시작되거나 목표가 갱신될 때 사용하세요.

나쁜 예시는 너무 추상적입니다.

필요할 때 예쁘게 보여주세요.

3. Props Schema

AI에게 어떤 값을 채워야 하는지 알려줍니다.

{
  "title": { "type": "string", "description": "퀘스트 제목" },
  "description": { "type": "string", "description": "해야 할 일 설명" },
  "reward": { "type": "string", "description": "성공 보상" }
}

4. Preview Props

미리보기에서 사용할 테스트 값입니다.

{
  "title": "잃어버린 열쇠 찾기",
  "description": "도서관에서 사라진 은색 열쇠를 찾아야 합니다.",
  "reward": "신뢰도 +5"
}

5. JSX 코드

아래는 아주 단순한 카드 예시입니다.

export default function QuestCard({ title, description, reward }) {
  return (
    <div className="rounded-2xl border border-amber-300 bg-amber-50 p-4 text-amber-950">
      <p className="text-xs font-bold uppercase tracking-wide">Quest</p>
      <h3 className="mt-1 text-lg font-bold">{title}</h3>
      <p className="mt-2 text-sm leading-relaxed">{description}</p>
      <p className="mt-3 rounded-lg bg-white/70 px-3 py-2 text-sm">보상: {reward}</p>
    </div>
  );
}

AI는 JSX를 어떻게 사용하나요?

컴포넌트를 활성화하면 NoahChat은 채팅 프롬프트에 컴포넌트 이름, 활용 지침, props 정보를 넣습니다.

그러면 AI는 적절한 장면에서 이런 형식의 표시를 넣습니다.

[[QuestCard:{"title":"잃어버린 열쇠 찾기","description":"도서관에서 은색 열쇠를 찾으세요.","reward":"신뢰도 +5"}]]

독자 화면에서는 이 태그가 그대로 보이는 것이 아니라, 등록한 카드 모양으로 렌더링됩니다.

버튼으로 메시지를 보내고 싶다면

JSX 안에서 sendMessage()를 사용하면, 독자가 버튼을 눌렀을 때 채팅 메시지를 보낼 수 있습니다.

export default function ChoiceButtons() {
  return (
    <div className="grid gap-2">
      <button onClick={() => sendMessage('문을 연다')}>문을 연다</button>
      <button onClick={() => sendMessage('잠시 기다린다')}>잠시 기다린다</button>
    </div>
  );
}

이 기능은 선택지형 작품, 미연시형 작품, TRPG형 작품에 잘 맞습니다.

저장 전 체크리스트

• 컴포넌트 이름이 영문으로 명확한가요?
• 활용 지침이 "언제 써야 하는지"를 알려주나요?
• Props Schema의 이름과 JSX 코드에서 쓰는 이름이 같나요?
• Preview Props로 미리보기가 정상 표시되나요?
• 채팅 해보기에서 AI가 너무 자주 쓰거나, 반대로 전혀 쓰지 않지는 않나요?
• JSX가 꼭 필요한 장면인가요? 상태창이나 일반 텍스트로 충분하지 않나요?

자주 생기는 문제

AI가 컴포넌트를 안 써요

활용 지침이 너무 모호할 수 있습니다. "중요한 정보가 있을 때"보다 "퀘스트가 새로 시작될 때"처럼 조건을 구체적으로 쓰세요.

AI가 너무 자주 써요

활용 지침에 제한을 넣으세요.

퀘스트가 새로 시작될 때만 사용하세요. 일반 대화 중에는 사용하지 마세요.

카드 내용이 비어 있어요

Props Schema에 필요한 값이 빠졌거나, 설명이 부족할 수 있습니다. 각 prop의 description을 더 구체적으로 써주세요.

미리보기는 되는데 채팅에서 이상해요

채팅 해보기에서 실제 AI가 어떤 값을 넣는지 확인하세요. 필요하면 활용 지침과 Props Schema를 함께 고쳐야 합니다.

먼저 만들기 좋은 JSX 예시

JSX가 어렵게 느껴진다면 먼저 상태창 자동 생성과 템플릿 라이브러리부터 사용해보세요.