공부하자

오픈클로(OpenClaw) 설치부터 제미나이 연동까지... 나만의 AI 비서 만들기(feat. 찍먹 후기)

solfa — Mon, 2 Feb 2026 02:42:52 +0900

안녕하세요! 요즘 AI 에이전트가 하도 핫해서 저도 한 번 찍먹해봤습니다.
이름은 OpenClaw(구 Clawdbot)인데, 내 로컬 PC에서 돌아가는 AI 비서라고 보면 돼요.

https://openclaw.ai/

OpenClaw — Personal AI Assistant

OpenClaw — The AI that actually does things. Your personal assistant on any platform.

openclaw.ai

왜 쓰냐?

내가 자는 동안 얘한테 시킬 수 있는 것들:

뉴스/깃허브 요약: "나 자는 동안 올라온 중요한 기술 뉴스나 관심 있는 Repo 업데이트 있으면 정리해 놔" 하면 아침에 일어나서 요약본만 읽으면 됩니다.
메일함 정리: 광고 메일 싹 날리고 중요한 메일만 골라놓게 시킬 수 있어요.
모니터링: 특정 사이트 가격 변동이나 티켓팅 오픈 같은 거 감시하게 시켜놓고 잠들면 됩니다. 항공권같은 거 이제 최저가 파악 가능

1. 일단 설치부터

준비물은 간단합니다. Node.js(22버전 이상)랑 Git-bash

그리고 가장 중요한 AI API Key가 필요해요. 제미나이, 클로드나 gpt도 됩니다!

설치 커맨드는 다음과 같습니다.

npm i -g openclaw
openclaw onboard

이렇게 치면 막 뭐라고 물어보는데, 그냥 QuickStart로 쭉쭉 넘기면 됩니다.

I understand this is powerful and inherently risky. Continue? -> Yes
Onboarding mode -> QuickStart

AI 모델(제미나이) 연결

Model/auth provider -> Google
Google auth method -> Google Gemini API key
Enter Gemini API key -> 아까 구글 AI 스튜디오에서 받아온 키를 복사-붙여넣기 하세요.
Default model -> 제미니는 구글 AI 스튜디오 Home > Quick Start 보면 현재 쓸 수 있는 모델명이 나와요
Select channel -> Skip for now (나중에 텔레그램이나 다른 거 연동할 때 해도 됩니다.)
Configure skills now? -> No (이것도 나중에 가능)

⑤ 훅(Hooks) 설정 (이건 3개 다 하세요!) Enable hooks? 라고 나오는데, 스페이스 바 눌러서 3개 다 체크하고 엔터 ㄱㄱ

boot-md: 봇 켜질 때 내가 만든 규칙(마크다운 파일)을 읽어와요. "너는 내 코딩 노예야" 같은 페르소나 주입용!
command-logger: 내가 시킨 거 다 기록해 줍니다.
session-memory: 대화 맥락을 기억해 줍니다.

2. 실제 구동 화면

설치가 완료되면 사진과 같은 대시보드 링크가 뜹니다.

Dashboard 모습! 좌측에 메뉴가 있고 상단에 `Health OK`가 떠야 정상입니다.

생각보다 UI가 깔끔해서 놀랐어요. 내가 만든 웹사이트보다 나은 듯

이제 연동된 제미나이랑 대화를 해봤습니다.

제 데덴네 귀엽죠??

3. 그래서 쓸만한가?

음... 학생 무료 제미니 api 갖다 쓰니 제 데덴네가 멈췄어요,,,

흑흑

내일 클로드 연결한 다음 다시 써볼게요...

그래도 이런 일 들 할 수 있어요

-> 내가 관심가진 채용공고들 싹 모아서 매일 8시에 알려줘 + 내가 기존 가진 이력서 줄테니 그걸로 각 회사에 맞게 지원서 써주고 아침마다 날 찾아와 이런 거 가능 ㅋㅋㅋㅋㅋ

4. 마치며

항공권 특가 cron 봇 만들어서 실제로 최저가에 결제해서 일본 가는 후기로 찾아오겠습니다...

설치하다가 막히는 거 있으면 댓글 남겨주세요! 아는 선에서 답변해 드릴게요.

#OpenClaw #오픈클로 #제미나이 #Gemini #AI비서 #나만의AI #공부기록 #IT블로그 #소프트웨어학부

GitHub - openclaw/openclaw: Your own personal AI assistant. Any OS. Any Platform. The lobster way.

Your own personal AI assistant. Any OS. Any Platform. The lobster way. - GitHub - openclaw/openclaw: Your own personal AI assistant. Any OS. Any Platform. The lobster way.

github.com

AI 인테리어 디자인의 혁명: 2025년 최고의 도구 8선

solfa — Fri, 19 Sep 2025 16:12:16 +0900

상상만 하던 인테리어를 실제로 구현할 수 있다면 어떨까요? AI 인테리어 디자인 도구의 등장으로 이제 누구나 전문가 수준의 공간 디자인이 가능해졌습니다. 특히 오늘의집 AI (Ohouse AI)는 단순히 예쁜 이미지를 만드는 것을 넘어, 실제 구매 가능한 가구로 디자인을 구성해 바로 주문할 수 있다는 점에서 게임 체인저가 되고 있습니다. 이 글에서는 2025년 주목해야 할 AI 인테리어 도구 8가지를 소개하고, 왜 오늘의집 AI가 한국 사용자에게 최고의 선택인지 자세히 알아보겠습니다.

2025년 최고의 AI 인테리어 디자인 도구 8선

1. 오늘의집 AI (Ohouse AI) - 강력 추천

"디자인에서 구매까지, 꿈이 현실이 되는 유일한 플랫폼"

오늘의집 AI는 단순한 AI 인테리어 디자인 도구가 아닙니다. 한국 최대 인테리어 커머스 플랫폼인 오늘의집이 보유한 200만 개 이상의 실제 판매 상품 데이터를 기반으로 작동하는, 진짜 '살 수 있는' 인테리어를 만들어주는 혁신적인 서비스입니다.

오늘의집 AI만의 독보적인 장점:

1. 실제 구매 가능한 가구로만 디자인 구성 다른 AI 도구들이 가상의 가구로 그럴듯한 이미지만 생성한다면, 오늘의집 AI는 현재 오늘의집에서 판매 중인 실제 상품으로만 디자인을 구성합니다. 마음에 드는 소파를 발견했다면? 클릭 한 번으로 상품 페이지로 이동해 가격, 사이즈, 리뷰까지 확인하고 바로 구매할 수 있습니다.

2. 예산 맞춤 디자인 제안 "500만원 예산으로 거실 꾸미기"처럼 예산을 설정하면, AI가 해당 금액 내에서 구매 가능한 실제 상품들로 여러 가지 디자인 옵션을 제시합니다. 각 아이템의 정확한 가격이 표시되어 총 예산을 실시간으로 확인할 수 있습니다.

3. 한국 주거 환경 완벽 대응 25평 아파트, 원룸, 오피스텔 등 한국 특유의 주거 형태를 완벽히 이해하고 있습니다. 특히 베란다 확장, 안방 드레스룸, 현관 신발장 같은 한국형 공간 구성을 정확히 반영합니다.

오늘의집 AI 사용 가이드

STEP 1: 공간 사진 업로드 및 정보 입력

웹브라우저에서 ohouse.ai/ai-interior 접속 (설치 불필요!)
현재 방 사진 업로드 또는 평수/구조 선택
"25평 아파트 거실" 같은 구체적 정보 입력

STEP 2: 스타일과 예산 설정

북유럽, 모던, 내추럴 등 선호 스타일 선택
예산 범위 설정 (예: 300-500만원)
선호 브랜드나 특정 가구 유형 지정 가능

STEP 3: AI 디자인 생성 및 상품 확인

3초 만에 5-10개의 디자인 옵션 생성
각 가구 위에 마우스를 올리면 실제 상품명과 가격 표시
마음에 드는 아이템 클릭 시 상품 상세 페이지로 바로 이동

STEP 4: 장바구니 담기 및 구매

전체 디자인 세트를 한 번에 장바구니 추가 가능
개별 아이템 선택적 구매 가능
오늘의집 포인트 적립 및 할인 혜택 자동 적용

STEP 5: 시공 서비스 연결 (선택사항)

필요시 인테리어 시공 견적 요청
검증된 오늘의집 파트너 시공사 매칭
3D 디자인을 기반으로 정확한 견적 산출

2. Dreamina

Dreamina는 글로벌 시장을 타겟으로 한 범용 AI 디자인 도구입니다. 다양한 편집 기능이 강점이지만, 생성된 가구를 실제로 구매할 수 없다는 한계가 있습니다.

주요 기능:

AI 인페인팅으로 부분 수정
고해상도 업스케일링
다양한 아트 스타일 지원

한계점: 실제 구매 연결 불가, 한국 주거 환경 이해 부족

3. Planner 5D

2D/3D 전환이 자유로운 디자인 툴이지만, 가상의 가구 라이브러리만 제공합니다.

주요 기능:

6,000개 가상 가구 아이템
평면도 작성 기능
VR 모드 지원

한계점: 실제 상품 정보 없음, 한국 가구 브랜드 부재

4. RoomGPT

빠른 디자인 생성이 장점이지만, 상업적 활용이 제한적입니다.

주요 기능:

2-3분 내 빠른 결과
간단한 인터페이스
다양한 스타일 옵션

한계점: 디자인만 제공, 구매나 시공 연결 없음

5. Homestyler

전문가용 고품질 렌더링 도구지만, 해외 브랜드 위주입니다.

주요 기능:

12K 초고해상도 렌더링
해외 브랜드 가구 라이브러리
VR 투어 기능

한계점: 한국 브랜드 부족, 실제 구매 프로세스 복잡

6. Foyr Neo

인테리어 전문가용 도구로 일반 사용자에게는 과도한 기능입니다.

주요 기능:

60,000개 3D 모델
전문가용 렌더링
팀 협업 기능

한계점: 높은 월 구독료 (월 $49~), 학습 곡선 높음

7. Autodesk Revit

건축 전문 BIM 소프트웨어로 일반 사용자용이 아닙니다.

주요 기능:

정밀 건축 설계
BIM 통합
전문가 협업

한계점: 매우 비싼 라이선스, 전문 교육 필요

8. DecorMatters

AR 기능은 재미있지만 실용성이 떨어집니다.

주요 기능:

AR 가구 배치
커뮤니티 챌린지
게임화 요소

한계점: 정확도 낮음, 한국 시장 미지원

오늘의집 AI가 특별한 이유: 상상을 현실로

1. 실제 구매 데이터 기반 AI 학습

오늘의집 AI는 1,000만 사용자의 실제 구매 패턴과 200만 개 상품 데이터를 학습했습니다. 이는 단순히 예쁜 이미지를 만드는 것이 아니라, 실제로 한국인이 선호하고 구매하는 인테리어를 제안한다는 의미입니다.

2. 원클릭 구매 시스템

"이 디자인 마음에 들어요!" → "전체 구매하기" → 3일 후 배송 완료

이 모든 과정이 오늘의집 AI에서는 현실입니다. 디자인에 사용된 모든 가구와 소품을:

개별 구매 가능
세트 구매 시 추가 할인
오늘의집 포인트 적립
무료 배송 (조건 충족 시)

3. 가격 투명성

각 디자인 옵션마다:

총 예산 실시간 표시
아이템별 정가와 할인가 비교
대체 가능한 저렴한 옵션 제시
시즌 세일 상품 우선 추천

4. 실제 사용자 리뷰 연동

AI가 제안한 가구들의:

실제 구매자 리뷰 즉시 확인
별점 및 만족도 표시
실제 사용 사진 확인 가능
사이즈, 색상 관련 구매 팁 제공

5. 통합 시공 서비스

디자인이 마음에 든다면:

오늘의집 인테리어 시공 견적 요청
AI 디자인 기반 정확한 비용 산출
검증된 파트너사 매칭
시공 진행 상황 실시간 확인

나에게 맞는 AI 인테리어 도구 선택 가이드

오늘의집 AI를 선택해야 하는 경우:

✅ 실제로 가구를 구매할 계획이 있는 경우 ✅ 예산 내에서 최적의 디자인을 원하는 경우 ✅ 한국형 아파트/주택에 거주하는 경우 ✅ 디자인부터 구매, 시공까지 원스톱 서비스를 원하는 경우 ✅ 실제 사용자 리뷰를 보고 구매 결정을 하고 싶은 경우

다른 도구를 고려해볼 경우:

단순 아이디어 스케치만 필요: RoomGPT
전문 건축 설계: Autodesk Revit
해외 거주자: Homestyler, Planner 5D
순수 창작 목적: Dreamina

실제 사용자 후기

김민지 (32세, 서울) "오늘의집 AI로 거실 디자인 만들고 마음에 들어서 세트로 구매했어요. 상상했던 그대로 우리 집이 바뀌었고, 총 비용도 예산 내였어요!"

박준호 (28세, 경기) "다른 AI 툴은 그림만 예쁘게 나오는데, 오늘의집 AI는 진짜 살 수 있는 가구로 보여줘서 실용적이에요. 디자인 본 그대로 구매할 수 있다는 게 최고!"

결론

AI 인테리어 디자인의 미래는 단순히 예쁜 이미지를 생성하는 것이 아닙니다. 실제로 구현 가능한, 구매 가능한, 예산에 맞는 현실적인 디자인을 제공하는 것입니다.

오늘의집 AI는 이 모든 것을 가능하게 하는 유일한 플랫폼입니다. 200만 개의 실제 상품, 1,000만 사용자의 구매 데이터, 검증된 시공 파트너, 그리고 강력한 AI 기술이 결합되어 당신의 상상을 현실로 만들어드립니다.

지금 바로 ohouse.ai/ai-interior 에서 무료로 시작해보세요. 설치 없이 웹브라우저에서 바로 사용 가능하며, 첫 디자인은 완전 무료입니다!

자주 묻는 질문

Q1. 오늘의집 AI에서 만든 디자인 그대로 구매할 수 있나요? 네, 100% 가능합니다! AI가 생성한 디자인의 모든 가구와 소품은 현재 오늘의집에서 판매 중인 실제 상품입니다. 각 아이템을 클릭하면 바로 상품 페이지로 이동하여 상세 정보를 확인하고 구매할 수 있습니다. 세트 구매 시 추가 할인도 제공됩니다.

Q2. 예산을 설정하면 정말 그 안에서 디자인을 만들어주나요? 네, 오늘의집 AI의 핵심 기능 중 하나입니다. 예를 들어 "300만원 예산"을 설정하면, AI가 실제 판매가 기준으로 300만원 이내의 상품들로만 디자인을 구성합니다. 각 디자인 옵션마다 정확한 총액이 표시되며, 예산을 초과하지 않는 대체 상품도 추천해드립니다.

Q3. 다른 AI 도구와 비교해서 디자인 퀄리티는 어떤가요? 오늘의집 AI는 실제 판매 상품의 고품질 이미지를 활용하기 때문에 매우 현실적이고 정확한 디자인을 생성합니다. 또한 1,000만 사용자의 실제 인테리어 데이터를 학습했기 때문에 한국 주거 환경에 최적화된, 실제로 적용 가능한 디자인을 제공합니다.

Q4. 사용료가 있나요? 기본 기능은 완전 무료입니다! 하루 10회까지 무료로 디자인을 생성할 수 있으며, 생성된 디자인의 상품을 구매하는 데는 추가 비용이 없습니다. 더 많은 디자인 생성이나 고급 기능을 원하시면 월 9,900원의 프리미엄 플랜을 이용하실 수 있습니다.

Q5. 시공 서비스도 연결되나요? 네, 오늘의집의 검증된 인테리어 시공 파트너를 통해 시공 서비스를 받으실 수 있습니다. AI 디자인을 바탕으로 정확한 견적을 받을 수 있으며, 오늘의집 앱에서 시공 진행 상황을 실시간으로 확인할 수 있습니다.

[React/리액트] React에서 순차적 API 호출 처리하기: 위치 기반 버스 도착 정보 조회 사례

solfa — Sun, 4 May 2025 20:13:06 +0900

React에서 순차적 API 호출 처리하기: 위치 기반 버스 도착 정보 조회 사례

서론

한 API의 결과가 다른 API를 호출하는 전제 조건이 되는 경우가 있다.

버스 번호판 인식 앱을 개발하다가 사용자의 위치를 먼저 서버에 전송하고, 그 위치 기반으로 버스 도착 정보를 조회해야 하는 상황이 발생했다. 이런 순차적 API 호출은 React에서 어떻게 처리할 수 있을까?

이번 글에서는 React Query의 Dependent Queries를 활용한 실제 구현 사례를 작성해보겠다.

문제 상황

요구사항 및 서비스 플로우이다.

사용자가 버스 번호를 입력하면 이 후에 위치 정보가 서버로 전송됨
서버에서 위치를 처리하는데 약간의 시간이 필요함
위치가 처리되면 해당 위치 기반으로 버스 도착 정보를 조회할 수 있음
하지만 위치 처리 전에 버스 도착 정보를 요청하면 빈 결과가 반환됨

다양한 해결 방법들

방법 1: 간단한 타임아웃 접근

// ❌ 안타깝게도 이 방법은 예측 불가능
useEffect(() => {
  locationTracker.startTracking();
  
  // 2초 후에 버스 정보 가져오기... 하지만 항상 충분한 시간일까?
  setTimeout(() => {
    getBusArrival();
  }, 2000);
}, []);

이 방법의 문제점

네트워크 상태에 따라 필요한 시간이 달라질 수 있음
너무 짧으면 데이터를 놓치고, 너무 길면 UX가 저하됨

방법 2: Promise 체이닝

useEffect(() => {
  let mounted = true;
  
  locationTracker.startTracking()
    .then(() => new Promise(resolve => setTimeout(resolve, 2000)))
    .then(() => mounted && getBusArrival())
    .then(data => mounted && setExpectedBuses(data))
    .catch(error => console.error(error));
    
  return () => { mounted = false; };
}, []);

장단점

장점: 명확한 실행 순서, 에러 처리 가능
단점: 콜백 지옥과 유사한 문제, 상태 관리가 복잡함

방법 3: async/await + 상태 관리

useEffect(() => {
  let mounted = true;
  
  const fetchData = async () => {
    try {
      await locationTracker.startTracking();
      await new Promise(resolve => setTimeout(resolve, 2000));
      if (mounted) {
        const data = await getBusArrival();
        setExpectedBuses(data);
      }
    } catch (error) {
      console.error(error);
    }
  };
  
  fetchData();
  return () => { mounted = false; };
}, []);

장단점

장점: 읽기 쉬운 코드, 비동기 처리가 자연스러움
단점: 여전히 타임아웃에 의존, 수동 상태 관리 필요

방법 4: React Query의 Dependent Queries (현재 적용한 방법)

1. 위치 상태 확인 쿼리

const { data: locationStatus } = useQuery({
  queryKey: ['locationStatus'],
  queryFn: async () => {
    // 위치 추적이 시작되지 않았다면 시작
    if (!locationTracker.isTracking()) {
      locationTracker.startTracking();
      await new Promise(resolve => setTimeout(resolve, 2000));
    }
    
    // 서버에서 위치를 처리했는지 확인
    try {
      await getBusArrival();
      return true; // 성공하면 위치가 처리된 것
    } catch {
      return false; // 실패하면 아직 처리 중
    }
  },
  refetchInterval: (data) => data ? false : 2000, // 성공하면 멈춤
  enabled: true,
});

위치 추적 여부를 먼저 확인하고, 추적 중이 아니면 자동으로 시작
getBusArrival()을 시험 삼아 호출하여 서버가 위치를 처리했는지 확인하는 창의적인 방법
성공하면 true를 반환하여 의존 쿼리 실행 허용
refetchInterval 함수를 사용하여 성공 후에는 폴링 중지

2. 의존성이 있는 버스 도착 정보 쿼리

const { data: expectedBuses = [] } = useQuery<BusInfo[]>({
  queryKey: ['busArrivals'],
  queryFn: getBusArrival,
  refetchInterval: 30000,
  enabled: locationStatus === true, //   핵심: 위치가 준비되었을 때만 실행
});

enabled 옵션으로 locationStatus가 true일 때만 실행되도록 설정
30초마다 새로운 버스 도착 정보를 가져오도록 자동 갱신 설정
기본값으로 빈 배열을 설정하여 undefined 에러 방지

React Query의 Dependent Queries란?

React Query 공식 문서에 따르면

"Dependent (or serial) queries depend on previous ones to finish before they can execute. To achieve this, it's as easy as using the enabled option to tell a query when it is ready to run."

https://tanstack.com/query/latest/docs/framework/react/guides/dependent-queries

Dependent Queries | TanStack Query React Docs

useQuery dependent Query Dependent (or serial) queries depend on previous ones to finish before they can execute. To achieve this, it's as easy as using the enabled option to tell a query when it is r...

tanstack.com

Dependent Queries는 특정 쿼리가 다른 쿼리의 결과에 의존하는 경우 사용된다. enabled 옵션을 사용하면 된다.

작동 원리

1. enabled 옵션이 false인 동안 쿼리는 실행되지 않는다.
2. enabled가 true로 변경되면 쿼리가 실행된다.
3. 이를 통해 데이터 fetch의 순서를 제어할 수 있다.

// locationStatus가 true일 때만 expectedBuses 쿼리 실행
enabled: locationStatus === true

상태 관리 흐름

초기 상태: status: 'pending', fetchStatus: 'idle'
의존성 충족 시: status: 'pending', fetchStatus: 'fetching'
데이터 로드 완료: status: 'success', fetchStatus: 'idle'

실제 구현 시 고려사항과 성능 최적화 팁

1. 폴링 최적화

refetchInterval: (data) => data ? false : 2000

최적화 포인트

위치가 확인되면 더 이상 폴링하지 않게 한다.
불필요한 네트워크 요청 제거로 성능 향상
조건부 폴링으로 리소스 절약

2. 쿼리 무효화 전략

const queryClient = useQueryClient();

// 위치 변경 시 버스 정보 무효화
locationTracker.onLocationChange(() => {
  queryClient.invalidateQueries(['busArrivals']);
});

데이터 일관성 유지

위치가 변경되면 기존의 버스 도착 정보는 더 이상 유효하지 않음
쿼리 무효화로 자동으로 새로운 데이터 요청
사용자에게 항상 최신 정보 제공

더 나은 해결 방안들

방법 5: Server-Sent Events (SSE)

// 클라이언트
useEffect(() => {
  // 위치 전송
  await postUserLocation({ latitude, longitude });
  
  // SSE 연결 - 서버가 준비되면 알림
  const eventSource = new EventSource('/api/bus-arrival-stream');
  
  eventSource.onmessage = (event) => {
    const data = JSON.parse(event.data);
    setExpectedBuses(data);
    eventSource.close();
  };
  
  eventSource.onerror = (error) => {
    console.error('SSE Error:', error);
    eventSource.close();
  };
  
  return () => eventSource.close();
}, []);

단점

장점: 실시간 통신, 서버 주도적 알림, 폴링 불필요
단점: 서버 구현 복잡도 증가, 추가 프로토콜 이해 필요

방법 6: WebSocket

// 클라이언트
useEffect(() => {
  const ws = new WebSocket('ws://localhost:3000/bus-updates');
  
  ws.onopen = () => {
    // 위치 정보 전송
    ws.send(JSON.stringify({ type: 'location', data: { latitude, longitude } }));
  };
  
  ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.type === 'bus-arrivals') {
      setExpectedBuses(data.payload);
      ws.close();
    }
  };
  
  return () => ws.close();
}, []);

장단점

장점: 양방향 통신, 실시간성, 더 복잡한 상호작용 가능
단점: 더 복잡한 구현, 인프라 고려사항 증가

방법 7: 서버에서 통합 엔드포인트 제공

// 서버
app.post('/api/bus-tracking', async (req, res) => {
  const { busNumber, latitude, longitude } = req.body;
  
  // 1. 위치 저장
  await saveUserLocation(userId, latitude, longitude);
  
  // 2. 통합 처리 후 결과 반환
  const busArrivals = await getBusArrivalsForLocation(userId, busNumber);
  
  res.json({ arrivals: busArrivals });
});

이 방법이 가장 깔끔한 이유

클라이언트 로직 단순화
한 번의 요청으로 처리 완료
서버에서 처리 시간 관리 가능

어떤 방식이 더 나을까?

현재 프로젝트에서의 선택 기준

서버 리소스가 제한적이라면: React Query + Dependent Queries
실시간성이 중요하고 서버 개선이 가능하다면: SSE 또는 WebSocket
가장 깔끔한 구조를 원한다면: 서버에서 통합 엔드포인트 제공

사실 이 문제의 근본적인 해결은 백엔드 API 설계의 개선에 있다. 클라이언트가 순차적 API 호출을 처리하는 것보다, 서버에서 모든 처리를 완료하고 한 번에 결과를 제공하는 것이 가장 이상적이다. 이는 클라이언트 로직을 단순화하고, 네트워크 레이턴시를 줄이며, 더 나은 사용자 경험을 제공한다. ㅎ 백엔드에게 바꿔달라 요청해봐야겠다.

자세한 코드는 pr 참고

https://github.com/Team-GomSun/FE/pull/18

feat: 버스 도착 전 위치 상태 확인 추가 by ssolfa · Pull Request #18 · Team-GomSun/FE

1️⃣ 어떤 작업을 했나요? (Summary) resolved refactor: API 요청 순서 지정 #17 위치 추적 후 버스 도착에 대한 종속 쿼리 구현 사용자 위치 정보 전송 후 이후에 주변 도착 버스 정보를 가져와야 하는데

github.com

결론

location 뒤에 버스 도착 정보인 arrival이 오는 걸 확신하는 코드가 되었다.

근데 아무리 생각해도 이런 경우 (주기적으로 get을 하는 것 보다)는

프론트에서 flag를 걸어서 확인하고 이후에 순차적으로 요청을 하는 것 보다

백엔드에서 조건이 성립했을 때 sse나 웹소켓으로 보내주는게 맞는 것 같다.

Claude 사용해서 Figma로 디자인 해달라고 하면 얼마나 잘 해줄까?

solfa — Tue, 22 Apr 2025 15:58:01 +0900

https://5ffthewall.tistory.com/137

Figma에 Cladue 연결해서 AI에게 디자인 생성해달라고 하기인데 이제 MCP를 곁들인…

오픈소스 과목에서 프로젝트 UI 디자인을 맡게 되었다.지금까지 개발자로만 이루어진 프로젝트를 하면서 항상 떠맡듯이 디자인을 맡아왔는데 이번에는 내가 자진해서 디자인을 해보고싶다고

5ffthewall.tistory.com

이전 글을 참고해서 클로드로 피그마 디자인을 하는 환경을 구축해뒀다.

이번에는 어느정도로 쓸만 한지를 직접 보여주겠다.

1. 디자인 시스템 주고 적용해서 디자인 해달라고 하기

사진과 같은 디자인 시스템이 담긴 링크를 클로드에게 주고 이 걸 활용해서 디자인을 해달라고 했다.

프롬프트는 다음과 같다.

(https://www.figma.com/design/aRDYrhvhDnIJLehFWvyLi3/~~ 링크 첨부)
이걸 보고 여기에 있는 디자인 시스템을 활용해서 앱 디자인을 만들어줘! 피그마에 바로 붙여넣을 수 있게 보내주고
앱 주제는 행복을 기록하는 감정 기록 일기장이야 앱 형식의 디자인을 보내줘! 만들어야 하는 화면은 1. 로그인 화면 2. 감정을 기록하는 기록 화면 (일기장처럼, 일기랑 감정 정도(숫자)를 입력받아) 3. 감정을 기록한 점수를 볼 수 있는 캘린더 화면, 점수에 따라 각 날짜의 진하기가 진해져 4. 개인정보를 담는 개인 페이지 5. 기록한 일기들을 스크롤형식으로 계속 볼 수 있는 저장소 화면 이렇게 5개 만들어줘

결과는 다음과 같다.

디자인 시스템을 온전히 가져다 쓴다기 보다는 색상만 골라 온 느낌?

플러그인이 없는 클로드라 디자인 요소들을 바로 가져다 쓸 수 없고 클로드 자체가 또 만들어내야 해서 그런 것 같기도 하다. 아쉽긴 하지만 주요 포인트 색상을 주고 프로토타입 정도 만드는 정도는 매우 만족할 것 같다.

2. 작업하던 디자인 주고 추가로 화면 만들어 달라고 하기

이건 내가 기존에 작업하던 피그마 화면이다. 여기에 추가로 화면을 만들어달라고 요청해봤다.

프롬프트는 다음과 같다.

https://www.figma.com/design/aRDYrhvhDnIJLehFWvyLi3/OpenS 링크링크
여기에 다른 화면들 그려진걸 보고 비슷한 느낌으로 로그인과 회원가입 화면을 두 개 만들어줘 회원가입은 구글, 카카오 두 개 넣을거야 피그마에 바로 붙여넣을 수 있게 보내줘!

결과는 다음과 같다.

뭐 나름... 있어야 하는 폼은 다 있고 전체적인 레이아웃은 괜찮은 것 같다. 가이드 정도는 받은 느낌? 디테일은 수정하면 되니까 이 정도면 나쁘지~~ 않을 수도

또 다른 페이지를 만들어달라고 해봤다.

프롬프트는 다음과 같다.

추가화면을 만들어줘
프로필 사진 업로드 옵션 - 회원가입 과정에서 프로필 사진을 설정할 수 있는 기능을 추가하면 사용자 참여도를 높일 수 있습니다. 이거 개인 페이지 화면과 이거를 만들어줘

결과는 다음과 같다.

뭐 이정도면 만족?? 글씨체도 기존에 설정되어있던 pretandard로 써준다. 플러그인 있는 커서로 쓰면 확실히 더 괜찮겠는걸...

3. 아무것도 없는 화면에 만들어 달라고 하기

프롬프트는 다음과 같다.

(pdf 첨부) -> 앱 방향성 담긴 프로젝트 소개/기능 문서였음
이런 앱을 만들거야. 앱 화면을 만들어주라.

결과는 다음과 같다.

가끔 가다가 흔들어서 활성화 이런 건 건질 수 있다. 본격 디자인 전에 한 번쯤은 돌려보고 괜찮은 레퍼런스 있으면 가져오고 이런 식으로 큰 기대 없이 쓰면 괜찮은 정도인 것 같다. 난 커서와 플러그인 같이 쓰는 그걸 너무 해보고 싶은데 커서 결제한 사람 누구야 어디있어!!! ㅜㅜㅜ

암튼 이정도로 사용할 수 있다는 걸 보여주고 싶었다.

가끔 가다 쓸 듯?

Docker와 ngrok을 활용한 react-webcam 개발 환경 구축

solfa — Fri, 18 Apr 2025 15:16:14 +0900

배경 및 문제 상황

React-Webcam 라이브러리를 사용해서 개발을 진행하던 중, 모바일 환경에서 테스트할 때 중요한 문제점을 발견했다.
모바일 브라우저에서 카메라 접근은 보안상의 이유로 HTTPS 프로토콜에서만 허용되기 때문에, 로컬 개발 환경이 기본적으로 사용하는 HTTP로는 모바일 테스트가 불가능했다. 이를 해결하기 위해 HTTPS 접속을 제공하는 ngrok을 사용하게 되었다.

사용 방법은 다음과 같다.

React Webcam 개발 환경 설정 가이드 - ngrok 사용 편

준비사항

Git
Node.js
pnpm (설치 방법: npm install -g pnpm)
ngrok 계정 (https://ngrok.com 에서 가입)

설정 단계

1. 프로젝트 클론하기

git clone https://github.com/Team-GomSun/FE 
cd FE

2. 의존성 설치하기

꼭 클론한 폴더 안에서 작성해주세요! (pnpm 없으면 설치해야 함)

pnpm install

3. 개발 서버 실행

pnpm run dev

실행하면 다음과 같이 뜬다.

4. ngrok 설치

Mac/Linux: brew install ngrok 또는 npm install -g ngrok
Windows: https://ngrok.com/download 에서 다운로드 후 설치

5. ngrok 인증 설정 (처음 한 번만)

ngrok config add-authtoken [YOUR_AUTH_TOKEN]

6. HTTPS 터널 실행

ngrok http 3000

7. 생성된 HTTPS 주소를 사용하여 모바일에서 접속

여기에서 Forwarding 된 주소!

그럼 이렇게 접속이 가능하다!

이렇게 기존 워크플로우는 다음과 같았다.

터미널에서 pnpm run dev 명령어로 개발 서버 실행
별도의 터미널을 열어 ngrok http 3000 명령어 실행해 HTTPS 터널 생성
생성된 ngrok URL을 통해 모바일에서 테스트

이 과정은 번거로울 뿐 아니라, 팀원마다 환경 설정이 달라 일관된 테스트 환경을 유지하기 어려웠다. 게다가 협업을 하게 되는 팀원 분은 pnpm 설치라던지 ngrok 설치 등 번거로운 설치 과정을 겪어야 같은 개발 환경을 구축할 수 있기 때문에 이런 점을 해결하기 위해 도커를 통해 개발 환경 구성을 해보려고 한다.

도커를 통해 개발 환경 구성하기 with ngrok

목표 설정

모바일 환경에서 카메라 테스트가 가능한 HTTPS 개발 환경 구축
팀원 간 일관된 개발 환경 제공
설정 과정 간소화 (최소한의 명령어)

검토한 솔루션은 세 가지가 있었다.

1. 수동 ngrok 설정 문서화 - 위에 쓴 거!!

장점: 추가 도구 없이 바로 적용 가능
단점: 여전히 여러 단계 필요, 환경 일관성 부족

2. 로컬 SSL 인증서 생성

장점: ngrok 의존성 제거, 안정적인 로컬 URL
단점: 모바일 기기에 인증서 설치 필요, 복잡한 설정 - 이건 좀 아니지

3. Docker + ngrok 통합 환경

장점: 일관된 환경, 간소화된 설정, 단일 명령어 실행
단점: Docker 학습 필요, 추가 시스템 자원 사용

채택한 솔루션: Docker + ngrok 통합 환경

Docker와 ngrok을 통합한 개발 환경을 구축하기로 결정했다. 이 방식은 환경 일관성과 설정 간소화라는 목표를 동시에 달성할 수 있었다.

구현 세부사항

개발 환경 구축을 위해 다음 파일들을 작성했다.

Dockerfile: Node.js 및 pnpm 기반 이미지 정의
docker-compose.yml: 애플리케이션과 ngrok 서비스 구성
setup.sh: 환경 변수 설정 및 Docker 실행 자동화
.dockerignore: 불필요한 파일 제외로 빌드 최적화

자세한 코드는 밑에서 확인할 수 있다.

https://github.com/Team-GomSun/FE/pull/6

feat: docker 개발 환경 구성 by ssolfa · Pull Request #6 · Team-GomSun/FE

1️⃣ 어떤 작업을 했나요? (Summary) resolved feat: Docker 개발 환경 구성 및 HTTPS 지원 추가 #5 React-Webcam이 모바일 환경에서 카메라에 접근하기 위해서는 HTTPS 프로토콜이 필수적입니다. 따라서 Docker와

github.com

중요한 의사결정 포인트

1. 왜 Docker를 선택했는가?

팀원마다 Node.js 버전과 패키지 관리자 설정이 달랐고, AI 구현 담당 팀원은 패키지 매니저 설치, ngrok 설치 등 번거로운 환경 설정을 거쳐야 했다. 편한 협업을 위해 Docker를 통한 개발 환경 표준화가 필요했다.

2. 왜 git clone 과정은 도커라이징하지 않았는가?

git 클론 과정까지 도커라이징하는 것도 가능했지만, 이런 접근 방식 대신 '개발자가 직접 git clone 후 setup.sh 실행'하는 방식을 선택한 이유는 다음과 같다.

개발 투명성 : 개발자가 코드를 직접 받아 확인하는 과정이 중요했다.
점진적 도입과 학습 곡선 고려 : 모든 것을 한 번에 도커라이징하면 학습 장벽이 높아질 수 있다. git clone은 개발자들에게 익숙한 작업이므로, 이 부분은 유지하고 환경 설정 부분만 자동화함으로써 도입 장벽을 낮추었다.
개발 환경에서만 도커 필요 : 배포 환경에서 필요한 게 아니라 모바일 테스트를 위한 개발 환경에서만 필요했기 때문에 기존 Git 기반 개발 워크플로우를 그대로 살리면서, 모바일 테스트 환경만 간소화하는 방향으로 접근했다.

이러한 장점이 추가적인 자동화로 얻을 수 있는 편의성보다 더 가치 있다고 판단했다.

3. 왜 Docker Compose를 사용했는가?

단일 Dockerfile만 사용하는 대신 Docker Compose를 도입한 이유는 다음과 같다.

다중 서비스 관리: 개발 서버(Next.js)와 HTTPS 터널링(ngrok)이라는 두 개의 서비스를 분리해 관리할 필요가 있었다.
네트워크 연결 자동화: Compose는 서비스 간 네트워크 연결을 자동 설정해주었다.
단일 명령어 제어: docker-compose up/down 명령어로 전체 환경을 한 번에 제어할 수 있었다.

대안으로 shell 스크립트를 이용해 Docker 명령을 순차적으로 실행하는 방법도 있었지만, 선언적이고 유지보수가 용이한 Compose 방식이 더 적합하다고 판단했다.

사용자 경험 개선

기존 복잡한 설정 과정을:

git clone [저장소URL]
cd [프로젝트폴더]
pnpm install
pnpm run dev
# 새 터미널 열기
ngrok http 3000

다음과 같이 간소화했다:

git clone [저장소URL]
cd [프로젝트폴더]
chmod +x setup.sh
./setup.sh YOUR_NGROK_AUTH_TOKEN

다시 작성한 개발 환경 가이드는 다음과 같다.

React Webcam 개발 환경 설정 가이드 - Docker 사용 편

pnpm, ngrok 등의 불필요한 설치를 피하기 위한 Docker 개발 환경 설정 가이드입니다. 이 가이드는 ReactWebcam 프로젝트를 Docker와 ngrok을 사용하여 HTTPS 환경으로 설정하는 방법을 안내합니다.

사전 준비사항

Docker 설치
- Docker Desktop 설치 (Windows/Mac)
- Linux의 경우 Docker Engine 설치
ngrok 계정 생성 및 인증 토큰 획득
- ngrok 회원가입
- 로그인 후 Your Authtoken 페이지에서 인증 토큰 확인

설치 및 실행 단계

1. 프로젝트 클론하기

git clone <https://github.com/Team-GomSun/FE>
cd FE

2. 환경 변수 설정

.env 파일을 만들어서 환경 변수를 설정해주세요.

# 프로젝트 루트에 .env 파일 생성
echo "NGROK_AUTH_TOKEN=YOUR_NGROK_AUTH_TOKEN" > .env

(YOUR_NGROK_AUTH_TOKEN 부분에 자신의 ngrok 인증 토큰을 입력하세요!)

3. 실행 권한 부여 및 애플리케이션 시작

터미널에 해당 명령어를 입력해주세요.

chmod +x setup.sh
./setup.sh

4. 확인 및 브라우저에서 접속

스크립트가 실행되면 약 10초 후에 다음과 같은 정보가 표시됩니다.

표시된 ngrok URL을 브라우저에서 열거나 모바일 기기에서 접속할 수 있습니다.

========================================
애플리케이션이 다음 URL에서 실행 중입니다:
<https://xxxx-xxx-xxx-xxx-xxx.ngrok-free.app> -> 여기 접속!
========================================

5. 환경 정리

프로젝트 작업을 마친 후 다음 명령어를 통해 환경을 정리해주세요.

docker-compose down

결론 및 교훈

이번 프로젝트를 통해 개발 환경 표준화의 중요성과 Docker의 유용성을 느꼈다. 써보고 싶던 도커 환경 구성을 해봐서 재밌었다.

이 설정은 프로덕션 환경이 아닌 개발 환경에 초점을 맞추고 있으며, Vercel 배포 과정에는 영향을 주지 않는다.

추후에는 프로덕션 환경에 대한 Docker 설정도 고려해볼 수 있을 것이다.

Figma에 Cladue 연결해서 AI에게 디자인 생성해달라고 하기인데 이제 MCP를 곁들인…

solfa — Wed, 9 Apr 2025 11:18:44 +0900

오픈소스 과목에서 프로젝트 UI 디자인을 맡게 되었다.

지금까지 개발자로만 이루어진 프로젝트를 하면서 항상 떠맡듯이 디자인을 맡아왔는데 이번에는 내가 자진해서 디자인을 해보고싶다고 했다. 그동안 디자인 시스템을 개발하거나 동아리 내의 디자인 시스템인 Handy를 사용하면서 디자인에 관심이 생기기도 했고 요즘 핫하다는 MCP를 사용해서 디자인을 AI로 만들어내고 싶었기 때문에 처음으로 자진해서 디자인을 해보고싶다고 했다.

그래서 오늘 할 건

Figma에 claude 연결하기!!

일단 MCP에 관해 간단히 설명을 해보고 넘어가겠다.

MCP(Model Context Protocol)란?

MCP는 Model Context Protocol의 약자로, 대형 언어 모델(LLM)이 외부 애플리케이션과 상호작용할 수 있게 해주는 표준화된 프로토콜이다. AI와 다른 소프트웨어가 서로 정보를 주고받을 수 있는 통로를 만들어준다고 생각하면 된다. 진짜 이해하기 쉽게 설명해보자면 내가 claude를 구독중이라면 이걸 아무 소프트웨어랑 붙여서 결합할 수 있게 하는 것! 다양한 소프트웨어에 코파일럿을 붙이는 느낌이다.

https://github.com/GLips/Figma-Context-MCP?tab=readme-ov-file#figma-mcp-server

GitHub - GLips/Figma-Context-MCP: MCP server to provide Figma layout information to AI coding agents like Cursor

MCP server to provide Figma layout information to AI coding agents like Cursor - GLips/Figma-Context-MCP

github.com

이렇게 만들어져있는 걸 사용하기만 하면 된다.

https://github.com/sonnylazuardi/cursor-talk-to-figma-mcp

Cursor는 이렇게 피그마에 플러그인도 있고 예제들도 많은데 Cladue는 많이 없다. 그래서 내가 해봤다!

Figma와 Cladue를 연결하기 ^_^

준비물

Figma 계정 (플랜은 상관 없음)
Figma API 액세스 토큰
Node.js (v16.0 이상)
Claude 계정 (pro? 무료도 되는지는 모르겠다)

1단계 : Figma API 토큰 받기

먼저 Figma API에 접근하기 위한 토큰이 필요하다. Figma 계정 설정에서 쉽게 발급받을 수 있다.

1-1. Figma에 로그인하고 프로필 아이콘을 클릭한다.

1-2. 설정(Settings) 메뉴로 이동한다.

1-3. 메뉴에서 '보안(Security)' 탭을 선택한다.

1-4. 아래로 스크롤하여 '개인 액세스 토큰(Personal access tokens)' 섹션을 찾는다.

1-5 '새 토큰 생성(Create a new personal access token)'을 클릭한다.

1-6. 토큰의 이름을 입력하고 '생성(Create)'을 클릭한다. -> 여기에서 접근 권한 (오른쪽 access는 모두 허용해둔다. write and read나 read only 모두 허용! 근데 안해도 될 것 같다. claude가 figma 캔버스에 직접 그리는 방법은 아니고 캔버스만 보고 새로운 디자인을 만들어주는거라! 지금 생각하니 read only만 해도 될 듯)

1-7. 생성된 토큰을 안전한 곳에 복사해 둔다. (이 토큰은 한 번만 표시되므로 꼭 저장해두기!)

2단계: IDE에 Figma MCP 서버 추가하기

이제 Figma와 Claude 사이의 다리 역할을 할 MCP 서버를 설정해보자. 나는 Figma-Context-MCP의 Quickstart를 참고했다.

https://www.framelink.ai/docs/quickstart?utm_source=github&utm_medium=readme&utm_campaign=readme

Quickstart - Framelink Figma MCP Reference

If you need more support to get your IDE configured, check out the official docs for your editor. You can also join our Discord if you need assistance.

www.framelink.ai

대부분의 IDE는 MCP 서버에 대한 JSON 설정을 지원한다. 이를 통해 Quickstart를 할 수 있게 된건데! IDE에서 MCP 구성 파일을 업데이트하면 MCP 서버가 자동으로 다운로드되고 활성화되는 방식이다.

2-1. Claude Desktop을 설치한다.

mcp 설정을 하기 위해서는 앱이 필요하다고 해서 깔았다.

앱 설치 후에 설정에 들어가면

개발자 섹션을 선택하면 설정 편집이 있는데 이걸 누르면

바로 설정을 편집할 수 있는 claude_desktop_config.json으로 이동시켜준다.

여기에 이것저것 명령어들을 넣어서 mcp를 사용하는 방식이다!

2-2. claude_desktop_config.json에 JSON 추가하기

Framelink Figma MCP 서버를 추가하기 위해서는

{
  "mcpServers": {
    "Framelink Figma MCP": {
      "command": "npx",
      "args": [
        "-y",
        "figma-developer-mcp",
        "--figma-api-key=YOUR-KEY",
        "--stdio"
      ]
    }
  }
}

이걸 붙여넣어준다. --figma-api-key에는 아까 발급받은 키를 넣어준다.

이렇게 하면 Claude와 같은 AI 도구가 자동으로 MCP 서버를 시작하는 식으로 동작한다!

npx라 깃허브 클론 받고 그럴 필요 없이 알아서 다운받고 처리해준다.

2-3. 클로드 앱 재시작하기

json을 변경한 후에는 꼭 앱을 종료 후 재시작해야한다!

그러면 이렇게 망치표시가 뜬다.

개발자 설정에 running이 뜨면 잘 돌아가고 있는 것이고

이렇게 망치 아이콘을 클릭하거나 커넥트 아이콘을 클릭해서 내가 추가한 mcp들을 확인할 수도 있다.

3단계: Claude에게 디자인 생성 요청하기

이제 Claude에게 Figma 디자인을 생성해달라고 요청해보자. 명령 전에 Claude에게 피그마 디자인을 링크를 통해 알려줘야 한다.

이런식으로 내가 원하는 부분의 링크를 Copy link to selection을 통해 복사한 후에 이걸 가지고 명령어를 입력하면 된다!

3-1. Claude를 열고 새 대화를 시작한다.

이런 식으로 링크와 함께 명령을 작성하면 된다.

그럼 22달러짜리 똑똑한 나의 사랑스러운 클로드가 피그마 파일을 분석해준다. 내가 보내준 링크에는 흰 바탕의 기본 프레임만 존재했다. 이걸 알고 알아서 피그마가 모바일 앱 화면을 뚝딱뚝딱 만들어줬다.

3-2. Figma에 코드를 복붙한다.

제공해준 SVG 코드 전체를 복사해서 피그마에 붙여넣기를 하면 피그마가 자동으로 SVG를 가져오고 편집 가능한 요소로 변환해준다!

생각보다 성능이 괜찮다는 걸 느꼈다.

디자인 작업 시 팁

디자인 작업 뿐만 아니라 프롬프팅을 해본 사람이라면 모두 공감할 것인데 ㅎ 0부터 10까지를 전부 만들어달라고 하기보다는

1. 이미 제작되어 있는 디자인의 다른 버전을 만들어 달라고 하자. - 이 디자인을 다크모드로 만들어줘. 포인트 색상은 #~~ 이걸로 수정해주고.

2. 레퍼런스를 먹이자. - 이건 아무것도 없는 상태에서 디자인을 만들어달라고 하기보다는 레퍼런스를 모아두고 모아둔 링크를 줘서 이런 스타일로 만들어달라고 하면 더 효과적일 것 같다. + 참고 이미지나 스타일 가이드를 제공하자 - "Material Design 스타일로" 또는 "Apple의 Human Interface Guidelines를 따라" 같은 표현을 사용하자.

3. MCP를 중첩으로 사용하자. - 22달러 뽕을 뽑아야 한다!!! 디자인 시스템이 존재한다면 그걸 mcp를 통해 먹이든 뭘 먹이든 먹여서 피그마에 만들어달라 하자!!!

처음에는 서버 설정이 조금 까다로웠지만, 한 번 설정을 마치고 나니 너무 재밌었고 여러 MCP들도 다양하게 사용해보고 싶어졌다.

https://github.com/punkpeye/awesome-mcp-servers

GitHub - punkpeye/awesome-mcp-servers: A collection of MCP servers.

A collection of MCP servers. Contribute to punkpeye/awesome-mcp-servers development by creating an account on GitHub.

github.com

이런 어썸한 mcp 들을 모아두는 깃허브도 존재하니 심심할 때 마다 자주 찾아봐야겠다.

마치며

AI가 모든 디자인 작업을 대체할 수는 없지만, 초기 아이디어 구상이나 프로토타입 제작을 훨씬 빠르게 할 수 있도록 도와준다는 점에서 그리고 개발자로만 이루어진 프로젝트를 하는 입장에서 이런 도구는 너무나 감사하고... 더 써보고 후기로 찾아오겠다.

https://ohouse.ai/ai-interior

Ohouse AI - AI Room Planner | Web Version

Upload a room photo and let Ohouse AI instantly transform it into stunning interior styles. Try AI-powered design for free in your browser!

ohouse.ai

[Next.js] Parallel Routes를 활용한 모달 상태 관리 하기 - URL 기반상태관리 / useSearchParams 와 Suspense 같이 사용하기

solfa — Tue, 18 Mar 2025 16:39:49 +0900

서론

모달(Modal)은 사용자에게 중요한 정보를 표시하거나 작업을 완료하도록 유도하는 UI 요소로 널리 사용된다.

하지만 모달의 상태 관리는 생각보다 복잡할 수 있다. 보통 모달의 열림/닫힘 상태를 관리하기 위해 보통 boolean 값을 사용하는 방식을 많이 채택한다. 최근에는 URL을 기반으로 모달 상태를 관리하는 방법이 떠오르고 있다.

이번 글에서는 Next.js의 App Router에서 제공하는 Parallel Routes 기능을 활용하여 모달 상태 관리를 URL 기반으로 리팩토링한 경험을 공유하려 한다. 단순히 boolean 값으로 관리하던 모달 상태를 왜 URL 기반으로 바꾸었는지, 그리고 이러한 접근 방식이 어떤 이점을 가져다주는지 함께 살펴보자.

Parallel Routes란?

Next.js의 App Router에서 도입된 Parallel Routes는 동일한 레이아웃 내에서 여러 페이지를 동시에 렌더링할 수 있게 해주는 기능이다. 이 기능은 @폴더명 형식의 특수 폴더 구조를 통해 구현된다.

https://nextjs.org/docs/app/building-your-application/routing/parallel-routes

Routing: Parallel Routes | Next.js

Simultaneously render one or more pages in the same view that can be navigated independently. A pattern for highly dynamic applications.

nextjs.org

app/
├── layout.tsx
├── page.tsx
└── @modal
    ├── default.tsx
    └── page.tsx

이런 구조에서 layout.tsx는 다음과 같이 작성할 수 있다

export default function RootLayout({
  children,
  modal,
}: {
  children: React.ReactNode;
  modal: React.ReactNode;
}) {
  return (
    <html>
      <body>
        {children}
        {modal}
      </body>
    </html>
  );
}

modal 슬롯은 @modal 폴더의 컨텐츠를 렌더링하며, 이를 통해 메인 컨텐츠(children)와 모달을 동시에 표시할 수 있다.

boolean 상태에서 URL 기반 상태 관리로의 전환

기존 방식: boolean 상태를 사용한 모달 관리

일반적으로 React에서 모달을 관리할 때는 다음과 같이 boolean 상태를 사용한다:

const [isModalOpen, setIsModalOpen] = useState(false);

// 모달 열기
const openModal = () => setIsModalOpen(true);

// 모달 닫기
const closeModal = () => setIsModalOpen(false);

return (
  <>
    <button onClick={openModal}>모달 열기</button>
    {isModalOpen && <Modal onClose={closeModal} />}
  </>
);

이 방식은 간단하고 직관적이지만, 몇 가지 제한사항이 있다:

브라우저 히스토리와의 불일치: 모달이 열린 상태에서 뒤로 가기 버튼을 누르면 이전 페이지로 이동하며, 모달 상태는 URL에 반영되지 않는다.
상태 공유의 어려움: 여러 컴포넌트 간에 모달 상태를 공유하려면 상태 관리 라이브러리나 Context API를 사용해야 한다.
직접 링크의 어려움: 특정 모달이 열린 상태의 페이지로 직접 링크를 제공하기 어렵다.

결론 : 복잡하고 모달 열린 상태로 공유가 가능하게 하고싶음 -> URL 기반으로 바꾸자!

URL 기반 모달 상태 관리 구현 방법

1. 폴더 구조 설정

먼저, Parallel Routes를 위한 폴더 구조를 다음과 같이 설정했다:

src/app/
├── @modal
│   ├── default.tsx  // 모달이 없을 때 표시할 컴포넌트
│   └── page.tsx     // 모달 컴포넌트
├── layout.tsx       // 루트 레이아웃
└── page.tsx         // 메인 페이지

2. 기본 컴포넌트 설정 (default.tsx)

모달이 표시되지 않을 때는 default.tsx가 렌더링된다:

// src/app/@modal/default.tsx
export default function Default() {
  return null;
}

3. 모달 컴포넌트 구현 (page.tsx)

모달 컴포넌트는 URL 쿼리 파라미터를 확인하여 표시 여부를 결정한다:

// src/app/@modal/page.tsx
'use client';
import { useRouter, useSearchParams } from 'next/navigation';

export default function Modal() {
  const router = useRouter();
  const searchParams = useSearchParams();
  const isVisible = searchParams.get('duplicate') === 'true';
  
  if (!isVisible) return null;
  
  return (
    <div
      className="fixed inset-0 flex items-center justify-center bg-gray-500 bg-opacity-50"
      onClick={() => router.back()}
    >
      <div
        className="w-[90%] max-w-md rounded-xl bg-white p-6 text-center font-pretendard font-medium text-black shadow-lg"
        onClick={(e) => e.stopPropagation()}
      >
        <p className="text-4xl"> </p>
        <p className="mt-4 text-lg md:text-2xl">이미 등록된 전화번호입니다</p>
        <p className="text-lg md:text-2xl">다른 번호로 시도해주세요!</p>
        <button
          onClick={() => router.back()}
          className="mt-6 w-[210px] rounded-full bg-[#6B5CFF] py-3 text-lg font-semibold text-white hover:bg-[#5A52EE] md:w-full"
        >
          확인했어요
        </button>
      </div>
    </div>
  );
}

4. 레이아웃 설정 (layout.tsx)

루트 레이아웃에서는 children과 modal 슬롯을 모두 렌더링한다:

// src/app/layout.tsx
export default function RootLayout({
  children,
  modal,
}: {
  children: React.ReactNode;
  modal: React.ReactNode;
}) {
  console.log('modal slot exists:', !!modal);
  return (
    <html lang="ko">
      <body>
        {children}
        {modal}
      </body>
    </html>
  );
}

나는 첫 메인에서 모달을 사용했기 때문에 RootLayout에 modal을 추가해줬다.

5. 메인 페이지에서 모달 열기 (page.tsx)

이제 모달을 열기 위해서는 단순히 URL을 변경하면 된다:

// src/app/page.tsx (일부)
const handleSubmit = async (e: FormEvent) => {
  e.preventDefault();
  // ...
  
  try {
    const { error } = await supabase.from('users').insert([{ phone_number: phoneNumber }]);
    if (error) {
      if (error.code === '23505') {
        // 기존: setIsModalOpen(true);
        // 변경: URL로 상태 관리
        router.push('/?duplicate=true');
        return;
      }
      throw error;
    }
    // ...
  } catch (error) {
    // ...
  }
};

이전에는 setIsModalOpen(true)를 통해 상태를 변경했지만, 이제는 router.push('/?duplicate=true')를 통해 URL을 변경한다.

모달이 잘 뜨는 것을 확인할 수 있다.

https://ppussung-tarot.yourssu.com/?duplicate=true

해당 링크로 들어가면 바로 모달 창으로 접근하는 것도 볼 수 있다!

자세한 코드는 여기에서 확인할 수 있다.

https://github.com/yourssu/ppusyung-tarot/commit/11f6f60544090d45aa067b30c3771f8a310773e6

단일 모달 컴포넌트에서 다중 상태 처리하기

복수의 모달 타입을 하나의 컴포넌트에서 처리하는 방법이다. 모달 안의 컨텐츠만 달라져야 했었는데 이런 단일 모달 컴포넌트의 다중 상태를 어떻게 처리하는지 실제 프로젝트에서 활용한 코드를 살펴보자:

// src/app/@modal/page.tsx
'use client';
import { useRouter, useSearchParams } from 'next/navigation';
import { Suspense } from 'react';

function ModalContent() {
  const router = useRouter();
  const searchParams = useSearchParams();
  const isDuplicate = searchParams.get('duplicate') === 'true';
  const isResourceExhausted = searchParams.get('resourceExhausted') === 'true';

  if (!isDuplicate && !isResourceExhausted) return null;

  return (
    <div
      className="fixed inset-0 flex items-center justify-center bg-gray-500 bg-opacity-50"
      onClick={() => router.back()}
    >
      <div
        className="w-[90%] max-w-md rounded-xl bg-white p-6 text-center font-pretendard font-medium text-black shadow-lg"
        onClick={(e) => e.stopPropagation()}
      >
        {isDuplicate && (
          <>
            <p className="text-4xl"> </p>
            <p className="mt-4 text-lg md:text-2xl">이미 등록된 전화번호입니다</p>
            <p className="text-lg md:text-2xl">다른 번호로 시도해주세요!</p>
          </>
        )}

        {isResourceExhausted && (
          <>
            <p className="text-2xl"> </p>
            <p className="mt-4 text-base md:text-xl">서비스 자원이 모두 소진되었습니다.</p>
            <p className="text-base md:text-xl">뿌슝타로에 많은 관심 보내주셔서 감사합니다!</p>
          </>
        )}

        <button
          onClick={() => router.back()}
          className="mt-6 w-[210px] rounded-full bg-[#6B5CFF] py-3 text-lg font-semibold text-white hover:bg-[#5A52EE] md:w-full"
        >
          확인했어요
        </button>
      </div>
    </div>
  );
}

export default function Modal() {
  return (
    <Suspense>
      <ModalContent />
    </Suspense>
  );
}

이 접근 방식의 주요 특징은 다음과 같다:

조건부 렌더링: 여러 쿼리 파라미터를 확인하여 적절한 모달 콘텐츠를 조건부로 렌더링한다.
Suspense 활용: Suspense로 모달 콘텐츠를 감싸 클라이언트 컴포넌트 초기화 과정에서의 지연을 처리한다.
공통 UI 재사용: 모달의 기본 구조(배경, 컨테이너, 닫기 버튼 등)를 재사용하면서 내용만 조건부로 변경한다.

그럼 이번에는 ?resourceExhausted=true로 모달이 잘 생기는 것을 확인할 수 있다.

이 방식으로 모달을 열 때는 다음과 같이 다양한 모달을 쉽게 활성화할 수 있다.

// 중복 전화번호 모달 열기
router.push('/?duplicate=true');

// 자원 소진 모달 열기
router.push('/?resourceExhausted=true');

Suspense가 필요한 이유: 빌드 시 useSearchParams 오류 해결

모달 컴포넌트를 개발하면서 useSearchParams를 사용하다가 에러가 발생했다.

개발 환경에서는 괜찮았는데 빌드할 때 다음과 같은 오류가 발생했다.

이는 Next.js에서 클라이언트 컴포넌트에서 useSearchParams를 사용할 때 발생하는 특정 문제 때문이다.

Error: useSearchParams() should be wrapped in a suspense boundary at the same level as the component that uses it.

이 오류는 Next.js 13 이상에서 App Router를 사용할 때, useSearchParams 훅이 서스펜스(Suspense) 경계 내에서 사용되어야 한다는 것을 알려준다.

서버 컴포넌트와 클라이언트 컴포넌트의 하이드레이션: Next.js는 서버에서 초기 렌더링을 수행한 후 클라이언트에서 하이드레이션을 수행한다. 이 과정에서 useSearchParams는 클라이언트에서만 사용 가능한 정보에 의존한다.
스트리밍 렌더링 지원: Next.js 13부터는 스트리밍 렌더링을 지원하는데, Suspense를 사용하면 이 기능을 최대한 활용할 수 있다. useSearchParams가 준비되기 전에도 나머지 UI를 렌더링할 수 있게 된다.
클라이언트-서버 불일치 방지: Suspense는 클라이언트와 서버 간의 렌더링 불일치를 방지하는 데 도움을 준다.

결론

export default function Modal() {
  return (
    <Suspense> // suspense 추가
      <ModalContent />
    </Suspense>
  );
}

suspense를 추가해줘서 에러를 해결했다.

'use client'와 Suspense의 차이

의문이 생겼다. 'use client' 지시문을 추가했는데도 왜 Suspense가 필요한지에 대한 것이다.

실제로 이 두 가지는 다른 목적을 가지고 있다.

'use client' 지시문:
- 이는 해당 컴포넌트와 그 하위 컴포넌트들이 클라이언트 측에서 실행됨을 Next.js에 알려준다.
- 클라이언트 컴포넌트라고 표시해도!! Next.js는 여전히 서버에서 이 컴포넌트의 초기 HTML을 생성한 다음, 클라이언트에서 하이드레이션한다.
- 이걸 써도 Next.js는 여전히 서버에서 초기 HTML을 생성하려고 시도한다.
- 'use client'는 단순히 "이 컴포넌트는 클라이언트에서 상호작용이 필요하다"라고 알려주는 것이다.
Suspense boundary:
- Suspense는 비동기 작업이 진행되는 동안 로딩 상태를 처리할 수 있게 해주는 React 기능이다.
- Next.js App Router에서 useSearchParams()는 서버에서는 사용할 수 없고 클라이언트 하이드레이션이 완료된 후에만 올바른 값을 반환한다.
- Suspense가 없으면, Next.js는 전체 페이지를 클라이언트 측에서만 렌더링하도록 "강제로 전환"한다. => 이는 클라이언트 측 자바스크립트가 로드될 때까지 페이지가 비어 있을 수 있기 때문에 오류가 났다고 하는 것!
- Suspense를 사용하면 "이 특정 부분만 클라이언트에서 채워질 때까지 기다리고, 나머지 페이지는 정상적으로 서버에서 렌더링하라"고 알려준다.

useSearchParams()와 Suspense의 관계

useSearchParams()는 특별한 훅이다. 이 훅은 브라우저의 URL에서만 정보를 가져올 수 있기 때문에 서버에서는 사용할 수 없다.

-> useEffect와 다름!

Suspense 없이 useSearchParams()를 사용한다면?

이 컴포넌트는 서버에서 렌더링할 수 없는 클라이언트 데이터(URL 파라미터)에 의존하는데?
그렇다면 어떻게 해야 하지? 일단 서버 렌더링은 포기하고 전체를 클라이언트로 미루자.

Suspense를 사용한다면?

이 특정 부분은 클라이언트 데이터가 필요해서 서버에서 바로 렌더링할 수 없어.
하지만 이 부분만 나중에 클라이언트에서 채워줄게. 나머지 페이지는 계속 서버에서 렌더링해도 돼

정리하자면

'use client' = "이 코드는 클라이언트 기능이 필요해" (클라이언트 컴포넌트로 표시)
Suspense = "이 부분은 서버에서 즉시 렌더링할 수 없으니, 나중에 클라이언트에서 채워줘" (렌더링 전략 제어)

use client와 suspense를 둘 다 쓰는 이유도 이것 때문이다.

'use client'로 이벤트 핸들러, hooks 등을 사용 가능하게 하고
Suspense로 useSearchParams()가 클라이언트에서만 실행되도록 하면서도 페이지의 나머지 부분은 서버 렌더링의 이점을 누릴 수 있게 한다.

https://nextjs.org/docs/app/api-reference/functions/use-search-params

Functions: useSearchParams | Next.js

API Reference for the useSearchParams hook.

nextjs.org

Next.js 문서에는 useSearchParams, usePathname, useRouter와 같은 특정 네비게이션 관련 훅들이 Suspense와 함께 사용되어야 한다고 명시되어 있다.

반면, useState, useEffect 등 일반적인 React 훅들은 단순히 'use client' 지시문만 있으면 사용 가능하다.

일반 React 훅(useState, useEffect 등) = 'use client'만 필요
특정 Next.js 네비게이션 훅(useSearchParams 등) = 'use client' + Suspense가 필요

이렇게 생각하면 될 것 같다!

Next.js 프로젝트를 Vercel로 배포 자동화 + Route 53으로 도메인 변경

solfa — Sat, 8 Mar 2025 16:18:56 +0900

1. Vercel 배포를 선택한 이유

동아리 내에서 팀 organization을 사용하고 있다. 원래는 AWS S3 버킷을 생성하고 배포하는 방식으로 진행하려 했다. 하지만 이번 프로젝트는 Next.js를 사용하고 있으며, 특히 API Route 기능을 활용하고 있다. 이러한 특성상 단순한 정적 빌드가 어렵다고 판단했다.

Next.js의 SSR(Server Side Rendering) 및 API Route를 포함한 프로젝트는 기본적으로 서버 환경이 필요하다. AWS에서 이를 운영하려면 Lambda나 EC2 같은 추가적인 설정이 필요하지만, 이는 유지보수 비용과 복잡도를 증가시킨다. 하는 방법이 없진 않지만!! 빠른 배포가 우선이었기에 빠르고 간편한 Vercel 배포를 선택했다.

Vercel은 Next.js의 공식 배포 플랫폼으로, Next.js의 모든 기능을 손쉽게 지원한다. 추가적인 설정 없이도 SSR과 API Route를 지원하고, 배포 속도가 빠르며 무료 플랜에서도 기본적인 기능을 사용할 수 있다.

이러한 이유로 팀 레포에서 직접 배포하는 대신, 내 개인 레포로 포크한 후 Vercel에서 배포하는 방식으로 진행했다.

왜냐면... 팀 레포에서 버셀 배포는 비용이 들기 때문... 근데 이렇게 개인 레포로 포크해서 하는게 합법적인 불법 (?) 인 것 같다

ㅎ

ㅎ...

2. 배포 자동화를 위한 GitHub Actions 설정

GitHub Actions를 이용한 레포 동기화 및 배포 자동화

개인 레포에서 배포를 진행하다 보니, 팀 레포와의 코드 동기화가 필요했다. 이를 위해 GitHub Actions를 활용하여 팀 레포(main 브랜치)에 변경 사항이 생기면 자동으로 내 개인 레포에 반영되도록 설정했다.

이를 위해 .github/workflows/deploy.yml 파일을 추가했다.

이 워크플로우는 하나의 GitHub 저장소에서 다른 저장소로 코드를 자동으로 동기화하고 배포하는 자동화 과정이다.

deploy.yml 코드 설명

name: Auto-Sync and Deploy to Personal Repo
on:
  push:
    branches: ['main']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          persist-credentials: false
      - name: Create and copy files
        run: |
          mkdir -p output
          cp -R ./* ./.[^.]* output/ 2>/dev/null || :
          rm -rf output/output
      - name: Pushes to another repository
        uses: cpina/github-action-push-to-another-repository@main
        env:
          API_TOKEN_GITHUB: ${{ secrets.AUTO_ACTIONS }}
        with:
          source-directory: 'output'
          destination-github-username: ssolfa
          destination-repository-name: ppusyung-tarot
          user-email: ${{ secrets.EMAIL }}
          user-name: ssolfa
          commit-message: ${{ github.event.commits[0].message }}
          target-branch: main

주요 내용

push 이벤트 감지
main 브랜치에 push가 발생하면 이 workflow가 실행된다.
코드 체크아웃
actions/checkout@v4을 사용하여 팀 레포의 최신 코드를 가져온다.
파일 복사 및 준비
mkdir -p output을 통해 output 디렉토리를 생성하고, 프로젝트 파일을 복사한다.
개인 레포로 코드 푸시
cpina/github-action-push-to-another-repository@main 액션을 사용하여, 내 개인 레포(ppusyung-tarot)로 코드를 푸시한다.

미래의 나같은 사람들을 위해... 진짜 자세히 설명을 해보겠다

트리거 조건

on:
  push:
    branches: ['main']

이 워크플로우는 'main' 브랜치에 코드가 푸시될 때마다 자동으로 실행된다.
즉, 메인 브랜치에 변경사항이 생길 때마다 동기화 작업이 시작된다는 뜻!

작업 구성

jobs:
  build:
    runs-on: ubuntu-latest

'build'라는 하나의 작업을 정의하며, 최신 Ubuntu 환경에서 실행된다.

단계별 실행 과정

1. 코드 체크아웃

- name: Checkout code
  uses: actions/checkout@v4
  with:
    fetch-depth: 0
    persist-credentials: false

actions/checkout@v4: GitHub의 공식 체크아웃 액션을 사용하여 현재 저장소의 코드를 워크플로우 환경으로 가져온다.
fetch-depth: 0: 전체 커밋 기록을 가져온다. 완전한 저장소 복사본을 위해 필요하다. depth를 자유롭게 1로 할 수도 있다!
- fetch-depth: 1로 설정하면 최신 커밋만 가져오게 된다. 전체 Git 이력 대신 가장 최근 커밋만 체크아웃된다! 어차피 처음에 개인 레포로 포크 해올 때 전에 파일들은 전부 가져온 거나 다름이 없고! 현재 워크플로우에서는 단순히 파일을 복사하여 다른 저장소로 푸시하는 것이 목적이므로, fetch-depth: 1로 설정해도 기능적으로는 문제가 없 다. 오히려 이게 더 효율적일수도?!
persist-credentials: false: GitHub 기본 인증 정보를 유지하지 않는다. 이는 나중에 다른 인증 정보로 다른 저장소에 푸시하기 위함이다.
- 우리는 지금 두 개의 다른 저장소를 다루고 있다. 따라서 두 개의 다른 인증 정보가 필요하다. 기본 인증 대신 ${{ secrets.AUTO_ACTIONS }} 토큰을 사용하기 때문에 이걸 false로 설정해준다. true로 해도 되는지는... 안해봐서 모르겠다

2. 파일 복사 및 준비

- name: Create and copy files
  run: |
    mkdir -p output
    cp -R ./* ./.[^.]* output/ 2>/dev/null || :
    rm -rf output/output

output 디렉토리를 만들고 모든 파일을 여기로 복사해서 이 output 디렉토리의 내용을 ssolfa/ppusyung-tarot 저장소로 푸시할거다.

mkdir -p output: 'output'이라는 디렉토리를 생성한다.
cp -R ./* ./.[^.]* output/ 2>/dev/null || ::
- 현재 디렉토리의 모든 파일과 숨김 파일(.로 시작하는 파일)을 output 디렉토리로 복사한다.
- 2>/dev/null || :: 오류 메시지를 무시하고, 명령이 실패해도 워크플로우가 계속 진행되도록 한다.
rm -rf output/output: 중첩된 output 디렉토리를 제거하여 무한 복사를 방지한다.

복사 과정이 필요한 이유

기술적 필요성: cpina/github-action-push-to-another-repository 액션은 특정 디렉토리 내용만 다른 저장소로 푸시하도록 설계되었다. 따라서 푸시할 내용을 별도 디렉토리에 준비해야 한다.
선택적 파일 제외 가능: 복사 단계에서 특정 파일이나 디렉토리를 제외할 수 있습니다. 현재 스크립트는 단순히 모든 것을 복사하지만, 필요하다면 여기서 .git 폴더나 특정 설정 파일을 제외할 수 있다. -> 귀찮아서 안했지만 ㅠ

3. 다른 저장소로 푸시

- name: Pushes to another repository
  uses: cpina/github-action-push-to-another-repository@main
  env:
    API_TOKEN_GITHUB: ${{ secrets.AUTO_ACTIONS }}
  with:
    source-directory: 'output'
    destination-github-username: ssolfa
    destination-repository-name: ppusyung-tarot
    user-email: ${{ secrets.EMAIL }}
    user-name: ssolfa
    commit-message: ${{ github.event.commits[0].message }}
    target-branch: main

cpina/github-action-push-to-another-repository@main: 다른 저장소로 코드를 푸시하기 위한 커뮤니티 액션을 사용한다.
환경 변수:
- API_TOKEN_GITHUB: ${{ secrets.AUTO_ACTIONS }}: 대상 저장소에 접근하는 데 필요한 GitHub 액세스 토큰을 설정
설정 매개변수:
- source-directory: 'output': 이전 단계에서 준비한 (복사한) 디렉토리!
- destination-github-username: ssolfa: 대상 저장소의 소유자 -> 포크한 사람의 깃허브 닉네임
- destination-repository-name: ppusyung-tarot: 동기화할 대상 저장소의 이름 -> 포크한 레포 이름
- user-email & user-name: 커밋을 생성할 사용자의 정보 -> email도 명시해도 되는데 ㅜㅜ 이것만 개인정보라 가렸음 위에서 닉네임, 레포 이름 전부 시크릿 처리 해도 됨!
- commit-message: ${{ github.event.commits[0].message }}: 원본 커밋 메시지를 그대로 사용한다.
- target-branch: main: 대상 저장소의 어떤 브랜치에 푸시할지 지정

=> 따라서 이 워크플로우가 팀 레포의 'main' 브랜치에서 변경이 일어날 때마다 모든 파일을 'ssolfa/ppusyung-tarot' 저장소의 'main' 브랜치로 자동으로 복사해준다

GitHub Actions Secrets 설정하기

위의 workflow에서 secrets.AUTO_ACTIONS와 secrets.EMAIL을 사용하고 있다. 이를 설정하는 방법은 다음과 같다.

GitHub에서 개인 레포의 Settings → Secrets and variables → Actions로 이동한다.
New repository secret 버튼을 클릭하여 아래의 값을 추가한다.
- AUTO_ACTIONS: GitHub Personal Access Token (PAT)
- EMAIL: 커밋할 때 사용할 이메일 주소
AUTO_ACTIONS 발급 방법
- GitHub Settings → Developer settings → Personal access tokens에서 Fine-grained tokens를 생성한다.
- repo 권한을 부여하여 team repo에서 개인 repo로 코드 푸시가 가능하도록 설정한다.
- 생성된 토큰을 secrets.AUTO_ACTIONS에 등록한다.

이제 팀 레포에서 main 브랜치에 변경이 발생하면 자동으로 내 개인 레포에도 반영되며, 개인 레포에서 Vercel로 배포가 진행된다.

⬇️ 코드 전문 확인하기

https://github.com/yourssu/ppusyung-tarot/commit/74be5a7503993b3e9faeaeb1908d06a833ffe561

feat: 배포 자동화 yml 작성 · yourssu/ppusyung-tarot@74be5a7

ssolfa committed Feb 26, 2025

github.com

3. Route 53을 통한 도메인 연결

배포까지 했으면 도메인 연결이 필요하다. 기본적으로 Vercel이 제공하는 `project-name.vercel.app` 도메인 대신 우리 동아리 도메인을 사용해 볼 예정이다. 짜치는 도메인을 예쁘게 만들어보쟈

Vercel에서 도메인 추가하기

배포된 프로젝트의 Vercel 대시보드로 이동한다.

프로젝트 설정(Settings)에서 Domains 탭을 클릭한다.

"Add" 버튼을 클릭하고 원하는 서브도메인을 `[원하는이름].yourssu.com` 형태로 입력한다.

- 예: `tarot.yourssu.com` 또는 `ppusyung.yourssu.com`

도메인을 추가하면 "Invalid Configuration" 메시지가 표시된다. 다행히~ 정상이다! DNS 레코드가 아직 설정되지 않았기 때문이다.

Vercel이 제공하는 CNAME 값(일반적으로 `cname.vercel-dns.com.` 형식)을 사용해서 밑에서 도메인을 연결할 거다.

Route 53에서 CNAME 레코드 추가하기

보통은 A 레코드와 CNAME 레코드를 함께 추가해야 하지만, yourssu.com 도메인은 이미 존재하므로 A 레코드는 설정하지 않고 CNAME만 추가한다.

도메인 설정의 기본 개념
일반적인 도메인 설정에서는 두 가지 DNS 레코드가 필요하다.

A 레코드: 특정 IP 주소에 도메인을 매핑하는 역할 - 도메인(example.com)을 서버의 IP 주소에 직접 연결
CNAME 레코드: 기존 도메인을 다른 도메인으로 연결하는 역할 - 서브도메인(project.example.com)을 다른 도메인으로 연결

동아리에서는 이미 yourssu.com 도메인의 A 레코드가 설정되어 있다! 따라서 우리는 CNAME 레코드만 추가하면 된다.

a 레코드 추가하는 방법은 이 걸 참고하면 될 것 같다.

https://velog.io/@jangsebari/AWS-%EB%A5%BC-%EC%9D%B4%EC%9A%A9%ED%95%9C-%EC%A0%95%EC%A0%81-%EC%9B%B9-%EC%82%AC%EC%9D%B4%ED%8A%B8-%EB%8F%84%EB%A9%94%EC%9D%B8-%EC%97%B0%EA%B2%B0

AWS 를 이용한 정적 웹 사이트 도메인 연결

들어가며 개발자로 지내는 동안 aws 를 사용하여 프로젝트를 빌드해서 배포하고 서버와 함께 운영해 본 경험이 있었다. 우여곡절 끝에 어쩌다보니 실행이 됐다며 기뻐했던 기억이 나는데... 좋아

velog.io

Route 53에서 레코드 생성하기

AWS 콘솔에 접속하여 Route 53 서비스로 이동한다.

이미 도메인을 등록해둔 상태, dns 관리를 클릭해서 호스팅 영역으로 들어간다.

기존 호스팅 영역(yourssu.com)을 선택한다.

"레코드 생성" 버튼을 클릭한다.

레코드 이름은 버셀에서 설정한 원하는 서브도메인 (예: tarot)

레코드 유형은 CNAME 레코드

값은 버셀에서 준 value -> cname.vercel.-dns.com. (마지막 점 까지 입력)
TTL은 기본 300으로 설정

단순 라우팅(Simple Routing) 선택

이렇게 입력한 도메인과 Vercel에서 제공하는 도메인을 연결한다!

레코드를 생성하면 Vercel에서 설정한 도메인으로 정상적으로 접근 가능하다.

버셀 프로젝트 도메인에 들어가보면 Vercel의 도메인 상태가 "Invalid"에서 "Valid"로 변경되는 것도 볼 수 있다.

이제 원하는 서브 도메인으로 Vercel에 배포한 프로젝트에 접속할 수 있다!

[React] ky로 로그인 유지 구현하기 (with. JWT 인증)

solfa — Tue, 18 Feb 2025 19:48:19 +0900

API 요청을 할 때, 401 Unauthorized 응답이 오면 보통 액세스 토큰을 갱신(Refresh)하는 로직을 추가한다.

이 과정에서 ky 라이브러리를 활용하면 beforeRetry 훅을 사용해 비교적 간결하게 구현할 수 있다.

일단 ky에서 제공하는 BeforeRetryHook을 살펴보면

BeforeRetryHook에는 다음과 같은 타입이 정의되어 있다.

[ky 공식 문서](https://www.npmjs.com/package/ky#:~:text=users%27)%3B-,hooks.beforeRetry,-Type%3A%20Function)

Tiny and elegant HTTP client based on the Fetch API. Latest version: 1.7.5, last published: 6 days ago. Start using ky in your project by running `npm i ky`. There are 698 other projects in the npm registry using ky.

www.npmjs.com

여기에서 제공하는 retryCount를 사용 하냐 마냐가 오늘의 주제이다.

참고로 retryCount는 ky에서 자동으로 0부터 시작해 증가하는 값이다.

https://devpluto.tistory.com/entry/React-ky%EB%A1%9C-%EB%A1%9C%EA%B7%B8%EC%9D%B8-%EC%9C%A0%EC%A7%80-%EA%B5%AC%ED%98%84%ED%95%98%EA%B8%B0-with-JWT-%EC%9D%B8%EC%A6%9D

[React] ky로 로그인 유지 구현하기 (with. JWT 인증)

들어가며 ky는 fetch와 ESM을 기반으로 하는 HTTP Client를 제공하는 라이브러리입니다. 주로 사용되는 Axios의 interceptors와 비슷하게 ky는 응답을 intercept 하여 커스텀하게 조작이 가능한 AfterResponse, Befor

devpluto.tistory.com

처음에는 이 글을 참고해서 비슷하게 구현하려고 했고 내가 이해한 글의 코드처럼 마지막 재시도 전에 로그아웃을 수행하도록 구현했다.

const DEFAULT_API_RETRY_LIMIT = 2;

const handleTokenRefresh: BeforeRetryHook = async ({ error, retryCount }) => {
  // retryCount가 limit-1일 때(마지막 재시도 전) 로그아웃
  if (retryCount === DEFAULT_API_RETRY_LIMIT - 1) {
    authService.logout();
    return ky.stop;
  }

그러나... 모각코 시간에 이게 무슨 로직이냐는 질문에 난 대답을 할 수 없었고 ㅎ

retry.limit으로 이미 재시도 횟수를 제한하고 있는데, retryCount 체크가 필요할까?
코드처럼 마지막 재시도 전에 로그아웃하는 것이 좋은 방법일까?

라는 고민을 해보고자 한다.

고민을 하고 코드를 짰어야 했는데 ㅎ

ㅎ

두 가지 접근 방식 비교

일단 기존 코드였던 (retryCount === DEFAULT_API_RETRY_LIMIT - 1) 이렇게 마지막 재시도 전을 체크하는 방식을 알아보자.

✅ 첫 번째 방식 : retryCount를 체크해 마지막 재시도 전을 감지

const handleTokenRefresh: BeforeRetryHook = async ({ error, retryCount }) => {
  const httpError = error as HTTPError;

  if (httpError.response.status !== 401) {
    return ky.stop;
  }

  if (retryCount === DEFAULT_API_RETRY_LIMIT - 1) {
    authService.logout();
    return ky.stop;
  }

  const refreshToken = tokenService.getRefreshToken();
  if (!refreshToken) {
    authService.logout();
    return ky.stop;
  }

  try {
    await authService.refreshToken(refreshToken);
  } catch (error) {
    console.error("Token refresh 실패, 로그아웃", error);
    authService.logout();
    return ky.stop;
  }
};

이 방식의 특징

retryCount === DEFAULT_API_RETRY_LIMIT - 1 체크를 통해 마지막 재시도 전에 로그아웃을 수행한다.
마지막 요청을 수행하지 않고 미리 로그아웃하여 불필요한 요청을 방지한다.

이 방식의 흐름은 다음과 같다.

1️⃣ 첫 번째 API 요청 실패 (`401` 에러) → `retryCount = 0`
2️⃣ `refreshToken`으로 액세스 토큰 갱신 시도
3️⃣ 두 번째 시도 직전(`retryCount = 1`)
   - `retryCount === DEFAULT_API_RETRY_LIMIT - 1 (1 === 2-1)`이므로 조건이 참이 되고 로그아웃 실행
   - 마지막 요청을 보내지 않고 중단

마지막 시도를 생략하고 미리 로그아웃하는 것이 이 방식의 핵심이다.

결론적으로 DEFAULT_API_RETRY_LIMIT를 쓰는 이유는

=> 더 시도해봤자 실패할 거 같으니까 미리 포기하고 로그아웃 한다는 의미~ 라고 이해하면 되겠다.

주의할 점

ky.limit을 쓰지 않고 일부러 retryCount를 체크하는 의도는 이해했다.

마지막 시도 전을 감지해서 사용자 경험을 더 좋게 하려는 건데

limit 횟수가 3-4번도 아니고 2번일 거면 한 번만 시도하고 로그아웃하나 마지막 재시도 전을 감지해서 중지하나 똑같으니 최소 횟수를 4 이상으로 설정하자.

내 코드처럼 DEFAULT_API_RETRY_LIMIT가 2인 이상 retryCount를 체크하는 방식이 불필요하게 복잡함 대신

DEFAULT_API_RETRY_LIMIT = 4이면 3번까지는 시도해보고, 4번째 요청은 막으니까 이런 로직에 좋음

장점

refreshToken이 만료된 경우, 마지막 재시도를 하지 않고 즉시 로그아웃하니까

세션이 만료되었음을 빠르게 반영 → 사용자 경험(UX) 개선이 된다.

✅ 두 번째 방식: ky의 기본 동작을 따르는 방식

import ky, { type BeforeRetryHook, HTTPError } from "ky";
import { authService } from "./auth.service";
import { tokenService } from "./token.service";

const DEFAULT_API_RETRY_LIMIT = 2;

const handleTokenRefresh: BeforeRetryHook = async ({ error }) => {
  const httpError = error as HTTPError;

  if (httpError.response.status !== 401) {
    return ky.stop;
  }

  const refreshToken = tokenService.getRefreshToken();
  if (!refreshToken) {
    authService.logout();
    return ky.stop;
  }

  try {
    await authService.refreshToken(refreshToken);
  } catch (error) {
    console.error("Token refresh 실패, 로그아웃", error);
    authService.logout();
    return ky.stop;
  }
};

이 방식의 특징

retryCount를 따로 체크하지 않음 → ky의 기본 재시도 로직을 따름

장점

ky의 기본적인 retry.limit 설정을 활용하여 불필요한 로직이 없음

단점

refreshToken이 만료된 경우, 마지막 재시도를 수행한 후에야 로그아웃
즉, 마지막 요청이 의미 없이 실행될 가능성이 있음

이런 단점 때문에 처음 방식 (DEFAULT_API_RETRY_LIMIT을 체크하는 방식)을 고려하지 않았을까 싶다!

그래서 결론은 : 마지막 재시도 전에 로그아웃을 하는 것이 나을까?

일반적인 경우에는 ky의 기본적인 retry.limit 만 체크하는 것이 더 깔끔하고 직관적이다.

`retryCount`를 체크하지 않아도 `ky.retry.limit`이 이미 요청 횟수를 관리하기도 하니까. (물론 재시도 전을 감지하냐 마냐 차이가 있긴 하지만)

하지만 UX적으로 즉각적인 로그아웃이 필요하다면 앞서 말한 첫 번째 방식도 고려할 수 있다.

느낀점

ky 관련 예제나 코드가 많이 없어서 코드를 복붙해서 썼는데 어떤 로직인지 제대로 파악하지 않은채 쓴 건 실수였다.

사실 자료 없는 것도 한국어가 많이 없는 거지 문서 번역해서 보면 되긴 하는데... 귀찮아 한건 잘못된 행동 ㅎ

그래도 모각코 시간에 피드백을 받으면서 다시 고민해볼 기회가 생겼고 덕분에 어떤 방식이 더 나은지를 이해할 수 있었다!

[React/리액트] ky를 활용한 토큰 인증 시스템 구현하기 - Google OAuth와 Token Refresh

solfa — Thu, 13 Feb 2025 17:11:35 +0900

데이터 통신에는 항상 axios만 사용해왔는데 요즘에는 오히려 fetch만 쓰는게 덜 무겁다는 의견도 많이 나오고 axios는 과하다는 이야기가 많아서 이번 프로젝트에서는 fetch 기반의 ky 라이브러리를 사용해서 데이터 통신을 해보고자 한다.

ky란?

https://www.npmjs.com/package/ky

Tiny and elegant HTTP client based on the Fetch API. Latest version: 1.7.5, last published: a day ago. Start using ky in your project by running `npm i ky`. There are 693 other projects in the npm registry using ky.

www.npmjs.com

ky는 Sindre Sorhus가 만든 경량 HTTP 클라이언트 라이브러리로, fetch와 ESM을 기반으로 동작하며 사용성을 개선한 것이 특징이다. 기본적으로 JSON 변환, 타임아웃 처리, 간결한 API 인터페이스를 제공하여 번거로운 설정 없이도 효율적인 네트워크 요청을 수행할 수 있다. ⇒ axios보다 훨씬 가볍다는 소리!

axios vs fetch vs ky 비교

axios: 기능이 많지만 번들 사이즈가 큼
fetch: 가볍지만 기본적인 기능만 제공
ky: fetch의 장점(가벼움)을 가져오면서 편리한 기능들을 제공

ky 사용법

사용법은 다음과 같다.

ky를 설치하려면 다음 명령어를 실행한다.

npm install ky

ky는 요청 인터셉터, 재시도(retry) 기능, 헤더 설정 등을 지원하며, 필요에 따라 확장하여 사용할 수 있다.

간단한 요청 예제를 알아가보며 공부해보자.

GET 요청 보내기

import ky from 'ky';

const fetchData = async () => {
  try {
    const data = await ky.get('<https://jsonplaceholder.typicode.com/posts/1>').json();
    console.log(data);
  } catch (error) {
    console.error('Error fetching data:', error);
  }
};

fetchData();

여기서 .json()을 호출하면 response.json()을 자동으로 처리해준다.

POST 요청 보내기

import ky from 'ky';

const postData = async () => {
  try {
    const response = await ky.post('<https://jsonplaceholder.typicode.com/posts>', {
      json: {
        title: 'foo',
        body: 'bar',
        userId: 1,
      },
    }).json();

    console.log(response);
  } catch (error) {
    console.error('Error posting data:', error);
  }
};

postData();

json 옵션을 사용하면 자동으로 Content-Type: application/json 헤더가 추가된다.
응답도 JSON 형태로 자동 변환해준다.

기존 axios에서의 응답 처리와 비교해보면

import axios from 'axios';

const fetchData = async () => {
  const response = await axios.get('<https://jsonplaceholder.typicode.com/posts/1>');
  console.log(response.data); // JSON으로 자동 변환된 데이터
};

fetchData();

axios는 response.data에 JSON 데이터가 자동으로 변환되어 들어온다.
즉, const data = response.data;를 사용해야 JSON을 추출할 수 있음.

차이점 정리

라이브러리 JSON 변환 방식

ky	.json()을 직접 호출해야 JSON 변환됨
axios	응답 객체(response.data)에 JSON 변환된 데이터가 자동으로 들어감

토큰 저장 및 API 인스턴스 관리

보통 인증이 필요한 API를 호출할 때, 토큰을 헤더에 추가해야 한다.

이를 매번 설정하지 않고, ky 인스턴스를 만들어 관리하면 편리하다.

import ky from 'ky';

const api = ky.create({
  prefixUrl: '<https://api.example.com>', // API 기본 URL 설정
  headers: {
    Authorization: `Bearer ${localStorage.getItem('token')}`, // 저장된 토큰 사용
    'Content-Type': 'application/json',
  },
});

이후 인스턴스를 재사용 하기 위해서는 이렇게 하면 된다.

const fetchUserData = async () => {
  try {
    const data = await api.get('user/profile').json();
    console.log(data);
  } catch (error) {
    console.error('Error fetching user data:', error);
  }
};

fetchUserData();

✅ ky.create()를 사용하면

API의 기본 URL을 설정할 수 있다.
headers를 설정해서 토큰을 자동으로 포함할 수 있다.
필요하면 같은 설정을 공유하는 여러 개의 API 인스턴스를 만들 수도 있다.

요청 인터셉터 (Request Hook)

API 요청을 보낼 때 토큰을 동적으로 설정하거나, 요청을 변형할 때 사용한다.

const api = ky.create({
  prefixUrl: '<https://api.example.com>',
  hooks: {
    beforeRequest: [
      (request) => {
        const token = localStorage.getItem('token');
        if (token) {
          request.headers.set('Authorization', `Bearer ${token}`);
        }
      },
    ],
  },
});

✅ beforeRequest Hook을 사용하면

요청을 보내기 전에 헤더를 수정할 수 있다.
토큰이 있을 때만 Authorization 헤더를 추가할 수도 있다.

응답 인터셉터 (Response Hook)

API 응답을 받은 후, 에러 처리나 응답 변형을 할 때 사용한다.

const api = ky.create({
  prefixUrl: '<https://api.example.com>',
  hooks: {
    afterResponse: [
      async (request, options, response) => {
        if (response.status === 401) {
          console.error('Unauthorized! Redirecting to login...');
          window.location.href = '/login';
        }
      },
    ],
  },
});

✅ afterResponse Hook을 사용하면

응답 코드를 기반으로 자동 처리할 수 있다.
401 (Unauthorized) 발생 시, 자동으로 로그인 페이지로 리디렉트할 수도 있다.

재시도 (Retry) 기능

서버가 일시적으로 응답하지 않을 때, 자동으로 재시도하게 만들 수도 있다.

const api = ky.create({
  prefixUrl: '<https://api.example.com>',
  retry: {
    limit: 3, // 최대 3번 재시도
    methods: ['get', 'post'], // GET과 POST 요청만 재시도
    statusCodes: [408, 500, 502, 503, 504], // 재시도할 HTTP 상태 코드
  },
});

✅ retry 옵션을 사용하면

네트워크 불안정 문제를 자동으로 해결할 수 있다.
특정 HTTP 상태 코드가 발생했을 때만 재시도할 수도 있다.

헤더 설정 (Headers)

API 요청에 추가적인 헤더를 포함하고 싶을 때 사용할 수 있다.

const api = ky.create({
  prefixUrl: '<https://api.example.com>',
  headers: {
    'X-Custom-Header': 'MyCustomValue',
  },
});

요청을 보낼 때마다 X-Custom-Header: MyCustomValue가 자동으로 추가된다.

쿼리 파라미터 쉽게 추가하기

ky는 URL에 자동으로 쿼리 파라미터를 추가하는 기능을 제공한다.

const response = await ky.get('<https://api.example.com/users>', {
  searchParams: {
    page: 1,
    limit: 10,
  },
}).json();

✅ searchParams를 사용하면

URL을 직접 조작하지 않아도 쿼리 파라미터를 쉽게 추가할 수 있다.
https://api.example.com/users?page=1&limit=10 처럼 자동 변환된다.

정리

기능 방법

기본 GET 요청	ky.get(url).json();
POST 요청	ky.post(url, { json: { ... } }).json();
토큰 저장 & API 관리	ky.create({ headers: { Authorization: 'Bearer ...' } })
요청 인터셉터	beforeRequest: [ (request) => { ... } ]
응답 인터셉터	afterResponse: [ (request, options, response) => { ... } ]
재시도 (Retry)	retry: { limit: 3, statusCodes: [...] }
헤더 설정	headers: { 'X-Custom-Header': 'value' }
쿼리 파라미터 추가	searchParams: { key: value }

이론을 알았으니 실제로 도입해보자!

ky를 사용한 토큰 관리 + 구글 로그인 구현하기

현재 구현하고자 하는 것은 ky를 사용한 토큰 관리 + 구글 로그인 구현이다.

꼭 소셜 로그인이 아니어도 로그인 후 토큰 받아오는 로직은 다른 로그인들도 동일하니까 중간은 생략하고 나머지를 참고하면 좋을 것 같다.

구현 흐름은 이렇다.

1. 구글 로그인 → 토큰을 받아옴
2. 토큰을 저장
3. 이후 토큰을 포함하여 api 요청 (인스턴스 생성하기)
4. retry로 토큰 재발급하기

일단 기본 Url을 설정하기 위한 인스턴스를 생성한다.

1. 기본 인스턴스 생성

import { API_CONFIG } from "@/constants/config";
import ky from "ky";

export const api = ky.create({
  prefixUrl: API_CONFIG.BASE_URL,
});

API_CONFIG에는 BASE_URL과 구글 로그인에 필요한 GOOGLE_REDIRECT_URI를 넣어두었다.

export const API_CONFIG = {
  BASE_URL: import.meta.env.VITE_API_BASE_URL,
  GOOGLE_REDIRECT_URI: `${window.location.origin}/oauth/callback/google`,
};

2. Google OAuth 페이지로 리다이렉션을 도와주는 authservice를 만들기

import { API_CONFIG } from "@/constants/config";
import { api } from "./api";

export interface GoogleLoginResponse {
  accessToken: string;
  refreshToken: string;
}

export const authService = {
  // ... 코드 생략

  initiateGoogleLogin() {
    const redirectUrl = `${API_CONFIG.BASE_URL}/oauth2/google?redirect_uri=${API_CONFIG.GOOGLE_REDIRECT_URI}`;
    window.location.href = redirectUrl;
  },
};

initiateGoogleLogin 함수는 다음과 같은 URL을 생성한다.
${API_CONFIG.BASE_URL}/oauth2/google?redirect_uri=${API_CONFIG.GOOGLE_REDIRECT_URI}
사용자는 이 URL로 리다이렉션되어 Google 로그인 페이지를 보게 된다.

3. Google 인증 후 콜백 처리를 위한 컴포넌트 제작

import { authService } from "@/apis/auth.service.api";
import { useEffect, useRef } from "react";
import { useNavigate } from "react-router";

export const GoogleCallback = () => {
  const navigate = useNavigate();
  const processedRef = useRef(false);

  useEffect(() => {
    const handleGoogleCallback = async () => {
      const searchParams = new URLSearchParams(window.location.search);
      const code = searchParams.get("code");

      if (code && !processedRef.current) {
        processedRef.current = true;

        try {
          const { accessToken, refreshToken } = await authService.googleLogin(
            code
          );
          localStorage.setItem("accessToken", accessToken);
          localStorage.setItem("refreshToken", refreshToken);
          navigate("/");
        } catch (error) {
          console.error("Login failed:", error);
          navigate("/");
        }
      }
    };

    handleGoogleCallback();
  }, [navigate]);

  return <div>로그인 처리중</div>;
};

사용자가 Google에서 로그인을 완료하면, Google은 지정된 콜백 URL로 인증 코드와 함께 리다이렉션한다.
GoogleCallback 컴포넌트가 마운트되면 useEffect가 실행된다.
URL에서 인증 코드(code 파라미터)를 추출한다.
processedRef를 사용하여 콜백이 한 번만 처리되도록 보장한다.
⇒ 소셜 로그인에서 code를 추출해서 서버로 보내는 건 한 번만! 해야 된다. 따라서 stricemode가 켜져있거나 그런 상황에서는 오류가 발생할 수 있기 때문에 이렇게 ref를 사용해서 횟수를 감지하거나 useOnceEffect와 같은 한 번만 실행되는 useEffect를 사용하면 된다. useOnceEffect는 인터넷에 구현 코드가 많으니 찾으면 바로 나온다.

4. 백엔드 인증 처리 (auth.service.api.ts)

import { API_CONFIG } from "@/constants/config";
import { api } from "./api";

export interface GoogleLoginResponse {
  accessToken: string;
  refreshToken: string;
}

export const authService = {
// 아까 위에서 생략됐던 코드!
  async googleLogin(code: string): Promise<GoogleLoginResponse> {
    try {
      const response = await api
        .post("oauth2/login/google", {
          json: {
            authorizationCode: code,
          },
          throwHttpErrors: false,
        })
        .json<GoogleLoginResponse>();

      if (!response) {
        throw new Error("Login failed");
      }

      return response;
    } catch (error) {
      console.error("Google login error:", error);
      throw error;
    }
  },

  initiateGoogleLogin() {
    const redirectUrl = `${API_CONFIG.BASE_URL}/oauth2/google?redirect_uri=${API_CONFIG.GOOGLE_REDIRECT_URI}`;
    window.location.href = redirectUrl;
  },
};

추출된 코드로 authService.googleLogin(code)를 호출한다.
백엔드 API의 oauth2/login/google 엔드포인트로 POST 요청을 보낸다.
→ 보내면 서버가 토큰을 발급해줌!

5. 인증 완료 및 토큰 저장

import { authService } from "@/apis/auth.service.api";
import { useEffect, useRef } from "react";
import { useNavigate } from "react-router";

export const GoogleCallback = () => {
  const navigate = useNavigate();
  const processedRef = useRef(false);

  useEffect(() => {
    const handleGoogleCallback = async () => {
      const searchParams = new URLSearchParams(window.location.search);
      const code = searchParams.get("code");

      if (code && !processedRef.current) {
        processedRef.current = true;

        try {
          const { accessToken, refreshToken } = await authService.googleLogin(
            code
          );
          localStorage.setItem("accessToken", accessToken);
          localStorage.setItem("refreshToken", refreshToken);
          navigate("/");
        } catch (error) {
          console.error("Login failed:", error);
          navigate("/");
        }
      }
    };

    handleGoogleCallback();
  }, [navigate]);

  return <div>로그인 처리중</div>;
};

백엔드에서 성공적으로 응답을 받으면 accessToken과 refreshToken을 반환받는다.
이 토큰들을 localStorage에 저정하면 구현 끝~

이 부분은 기본 소셜 로그인 구현 로직이라 이 외의 로그인을 구현하고 있다면 토큰 받아온 이후부터 밑에 부분을 참고하면 좋을 것 같다.

Retry로 access token 재발급 로직 구현하기

위에서 말했듯이 ky는 beforeRetry 훅을 사용해 API fetch retry시 처리할 동작을 구현하는 것이 가능하다.

구현하고자 하는 상황은 다음과 같다.

1. status code가 401이 아닌 경우 retry를 중지한다.
2. access token 가져오는 것을 2번 이상 실패한다면 토큰 만료인 경우로 판단하여 로그아웃 처리를 한다. (token 삭제 등)
3. 1번과 2번 경우가 아닐 때는 refresh token을 사용해 access token을 가져오고 저장한다.

이를 위해 먼저 토큰을 관리하는 service를 만들어보자.

1. tokenService 만들기

export const tokenService = {
  getAccessToken: () => localStorage.getItem("accessToken"),

  getRefreshToken: () => localStorage.getItem("refreshToken"),

  setTokens: (accessToken: string, refreshToken: string) => {
    localStorage.setItem("accessToken", accessToken);
    localStorage.setItem("refreshToken", refreshToken);
  },

  clearTokens: () => {
    localStorage.removeItem("accessToken");
    localStorage.removeItem("refreshToken");
  },

  hasTokens: () => {
    const accessToken = localStorage.getItem("accessToken");
    const refreshToken = localStorage.getItem("refreshToken");
    return !!(accessToken && refreshToken);
  },
};

이제 토큰을 관리하는 service를 만들었으니, 토큰 재발급 로직을 구현해보자.

2. 토큰을 재발급 하는 로직 만들기

const DEFAULT_API_RETRY_LIMIT = 2;

const handleTokenRefresh: BeforeRetryHook = async ({ error, retryCount }) => {
  const httpError = error as HTTPError;

  if (httpError.response.status !== 401) {
    return ky.stop;
  }

  if (retryCount === DEFAULT_API_RETRY_LIMIT - 1) {
    authService.logout();
    return ky.stop;
  }

  try {
    const refreshToken = tokenService.getRefreshToken();
    if (!refreshToken) {
      throw new Error("refreshToken이 없음");
    }
    await authService.refreshToken(refreshToken);
  } catch (error) {
    console.error("Token refresh 실패, 로그아웃", error);
    authService.logout();
    return ky.stop;
  }
};

이렇게 만든 handleTokenRefresh를 ky 인스턴스에 등록하면 된다.

export const api = ky.create({
  prefixUrl: API_CONFIG.BASE_URL,
  retry: {
    limit: DEFAULT_API_RETRY_LIMIT,
  },
  hooks: {
    beforeRequest: [setAuthHeader],
    beforeRetry: [handleTokenRefresh],
  },
});

이제 토큰이 만료되었을 때 자동으로 재발급을 시도하고, 실패하면 로그아웃되는 로직이 구현되었다!

이렇게 구현한 auth 로직은 다음과 같은 특징을 가진다.

401 에러 발생시 자동으로 토큰을 재발급한다.
토큰 재발급 실패시 자동으로 로그아웃된다.
API 요청시 자동으로 토큰이 헤더에 포함된다.

이제 이 인스턴스를 사용해서 안전하게 API를 호출할 수 있다 ㅎㅎ

로그아웃 구현하기

로그아웃은 간단하다. 토큰을 삭제하고 홈으로 리다이렉트하면 된다.

logout: async () => {
  try {
    await api.post("logout", {
      json: { refreshToken: `${tokenService.getAccessToken()}` },
    });
  } catch (error) {
    console.error("Logout failed:", error);
  } finally {
    tokenService.clearTokens();
    window.location.href = "/";
  }
},

이렇게 구현한 auth 로직을 실제로 사용해보자. 네비게이션 바에 로그인/로그아웃 버튼을 추가해보자.

import { authService } from "@/apis/auth.service.api";
import { tokenService } from "@/apis/token.service";
import { StyledContainer, StyledProfileImage } from "./Navigation.style";

const Navigation = () => {
  const handleClick = () => {
    if (tokenService.hasTokens()) {
      authService.logout();
    } else {
      authService.initiateGoogleLogin();
    }
  };

  return (
    <StyledContainer>
      <StyledProfileImage onClick={handleClick}>
        <p>{tokenService.hasTokens() ? "로그인됨" : "로그인필요"}</p>
      </StyledProfileImage>
    </StyledContainer>
  );
};

export default Navigation;

토큰이 있으면 "로그인됨"이 표시되고 클릭하면 로그아웃되며, 토큰이 없으면 "로그인필요"가 표시되고 클릭하면 Google OAuth 페이지로 리다이렉트된다.

결과 화면

구글 로그인과 토큰 저장 로직이 잘 작동하는 것을 볼 수 있다.

마무리

ky 괜찮은 것 같다.

재밌다~~ axios랑 비슷해서 넘어오기 부담스럽지 않을 듯 하다.

전체 코드는 밑에서 확인할 수 있다.

https://github.com/yourssu/Yourssu-Scouter-Frontend/pull/9

feat: 구글 로그인 및 토큰 인증 서비스 구현 by ssolfa · Pull Request #9 · yourssu/Yourssu-Scouter-Frontend

1️⃣ 어떤 작업을 했나요? (Summary) resolved feat: 구글 로그인 구현 #8 2025-02-13.3.06.03.mov API 통신을 위한 ky 인스턴스 구현 ky의 prefixUrl, retry, hooks 옵션을 활용하여 base URL 설정, 재시도 로직,...

github.com

공부하자

오픈클로(OpenClaw) 설치부터 제미나이 연동까지... 나만의 AI 비서 만들기(feat. 찍먹 후기)

왜 쓰냐?

1. 일단 설치부터

2. 실제 구동 화면

3. 그래서 쓸만한가?

4. 마치며

AI 인테리어 디자인의 혁명: 2025년 최고의 도구 8선

목차

2025년 최고의 AI 인테리어 디자인 도구 8선

1. 오늘의집 AI (Ohouse AI) - 강력 추천

2. Dreamina

3. Planner 5D

4. RoomGPT

5. Homestyler

6. Foyr Neo

7. Autodesk Revit

8. DecorMatters

오늘의집 AI가 특별한 이유: 상상을 현실로

1. 실제 구매 데이터 기반 AI 학습

2. 원클릭 구매 시스템

3. 가격 투명성

4. 실제 사용자 리뷰 연동

5. 통합 시공 서비스

나에게 맞는 AI 인테리어 도구 선택 가이드

오늘의집 AI를 선택해야 하는 경우:

다른 도구를 고려해볼 경우:

실제 사용자 후기

결론

자주 묻는 질문

[React/리액트] React에서 순차적 API 호출 처리하기: 위치 기반 버스 도착 정보 조회 사례

React에서 순차적 API 호출 처리하기: 위치 기반 버스 도착 정보 조회 사례

서론

문제 상황

다양한 해결 방법들

방법 1: 간단한 타임아웃 접근

방법 2: Promise 체이닝

방법 3: async/await + 상태 관리

방법 4: React Query의 Dependent Queries (현재 적용한 방법)

React Query의 Dependent Queries란?

작동 원리

실제 구현 시 고려사항과 성능 최적화 팁

1. 폴링 최적화

2. 쿼리 무효화 전략

더 나은 해결 방안들

방법 5: Server-Sent Events (SSE)

방법 6: WebSocket

방법 7: 서버에서 통합 엔드포인트 제공

어떤 방식이 더 나을까?

현재 프로젝트에서의 선택 기준

결론

Claude 사용해서 Figma로 디자인 해달라고 하면 얼마나 잘 해줄까?

1. 디자인 시스템 주고 적용해서 디자인 해달라고 하기

2. 작업하던 디자인 주고 추가로 화면 만들어 달라고 하기

3. 아무것도 없는 화면에 만들어 달라고 하기

Docker와 ngrok을 활용한 react-webcam 개발 환경 구축

배경 및 문제 상황

React Webcam 개발 환경 설정 가이드 - ngrok 사용 편

도커를 통해 개발 환경 구성하기 with ngrok

목표 설정

검토한 솔루션은 세 가지가 있었다.

채택한 솔루션: Docker + ngrok 통합 환경

구현 세부사항

중요한 의사결정 포인트

1. 왜 Docker를 선택했는가?

2. 왜 git clone 과정은 도커라이징하지 않았는가?

3. 왜 Docker Compose를 사용했는가?

사용자 경험 개선

React Webcam 개발 환경 설정 가이드 - Docker 사용 편

사전 준비사항

설치 및 실행 단계

결론 및 교훈

Figma에 Cladue 연결해서 AI에게 디자인 생성해달라고 하기인데 이제 MCP를 곁들인…

Figma에 claude 연결하기!!

MCP(Model Context Protocol)란?

Figma와 Cladue를 연결하기 ^_^

1단계 : Figma API 토큰 받기

2단계: IDE에 Figma MCP 서버 추가하기

3단계: Claude에게 디자인 생성 요청하기

마치며