ej-rarus.log

[AX] 기획서, 사람이 쓰지 마세요: 5명의 AI 에이전트 팀 구축기

Wed, 24 Dec 2025 02:39:34 GMT

"기획서에 구멍이 너무 많아요." "이거 쇼피파이에서는 안 되는 기능인데요?" "예외 처리는 어떻게 하나요?"

개발자 분들에게 이런 피드백, 한 번쯤 들어보셨을 겁니다. 저 역시 마찬가지였습니다. 사람이 작성하는 기획서(Spec)는 필연적으로 주관이 개입되고, 논리적 빈틈이 생기기 마련이니까요.

오늘은 단순한 업무 보조 도구로서의 AI가 아닌, 시스템적으로 기획 프로세스를 혁신(AX, AI Experience)하기 위해 시도한 'Spec Owner 서브에이전트 체계' 도입 과정을 공유하려 합니다.

1. 왜 AX인가? (The Problem)

쇼피파이(Shopify) 에이전시로서 저희는 수많은 프로젝트를 진행합니다. 하지만 매번 반복되는 고질적인 문제들이 있었습니다.

기획자의 주관: 담당 기획자의 숙련도에 따라 스펙의 퀄리티가 들쑥날쑥함.
플랫폼 제약 미인지: 쇼피파이의 기술적 한계(Rate Limit, Schema 구조)를 고려하지 않은 기획.
엣지 케이스 누락: "설마 사용자가 이렇게까지 하겠어?"라는 안일함이 만드는 치명적인 버그.

우리는 결심했습니다. "완벽한 스펙을 위해 기획자의 역할을 해체하고, AI에게 전문성을 부여하자."

2. 'Spec Owner'를 5명의 AI로 분열시키다

단순히 "AI에게 기획서 써줘"라고 명령하는 것만으로는 충분하지 않습니다. 우리는 Spec Owner(기획 총괄)의 역할을 5개의 전문화된 페르소나(Sub-Agent)로 쪼개고, 이들이 서로 견제하고 협력하는 시스템을 구축했습니다.

🤖 Team Spec Owner 라인업

코드명	역할 (Role)	성격 및 특징
Scope Guard	경계 관리자	"그 기능, 비즈니스 목표에 정말 필수인가요?" 불필요한 스펙을 쳐내고 범위를 확정합니다.
Shopify Architect	데이터 설계자	"이건 Metaobjects로 구현해야 효율적입니다." 요구사항을 쇼피파이 DB 구조와 API에 매핑합니다.
Edge Case Hunter	예외 사냥꾼	"네트워크가 끊기면요? 결제가 0원이면요?" 비관적인 시각으로 실패 시나리오를 찾아냅니다.
WBS Orchestrator	일정 관리자	"이 작업은 3일 소요됩니다." 작업 단위(Task)를 쪼개고 실행 순서를 정렬합니다.
AC Standardizer	검증 표준화	"딱 잘라 말해서, 합격 아니면 불합격." 애매한 표현을 배제하고 정량적 테스트 기준을 세웁니다.

3. 어떻게 일하나요? (Workflow)

이 시스템의 핵심은 '단계별 검증(Sequential Verification)'입니다.

Input: 고객의 날것 그대로의 요구사항이 입력됩니다.
Filter (Scope Guard): "이건 현재 범위 밖입니다"라고 1차 필터링을 거칩니다.
Design (Architect): 쇼피파이 환경에서 구현 가능한 최적의 스키마를 설계합니다.
Attack (Hunter): 설계된 스펙을 공격하여 논리적 구멍을 찾습니다.
Plan (Orchestrator): 개발/디자인 팀이 바로 착수할 수 있게 작업을 세분화합니다.
Criteria (Standardizer): QA 팀이 사용할 무결한 체크리스트를 출력합니다.

이 모든 과정에서 사람은 '최종 의사결정(Decision Making)'에만 집중합니다.

4. 도입 효과 (Expected Benefits)

이 체계를 정의하고 실무에 시범 도입해본 결과, 다음과 같은 긍정적인 변화를 기대하고 있습니다.

논리적 결함 90% 사전 차단: 개발자가 코드를 짜기 전에, Edge Case Hunter가 논리적 오류를 미리 잡아냅니다.
커뮤니케이션 비용 절감: "이 부분 어떻게 처리해요?"라는 질문 대신, 명확한 API 스케치와 AC(Acceptance Criteria)가 공유됩니다.
스펙의 표준화: 어떤 기획자가 투입되더라도 일정한 수준 이상의 결과물이 보장됩니다.

5. 마치며: AI-Native로 가는 길

AX(AI Experience)는 단순히 AI 툴을 사용하는 기술적 변화가 아니라, '일하는 방식의 근본적인 재정의'였습니다.

저희 팀은 이제 기획서의 '초안'을 직접 쓰지 않습니다. AI 에이전트들이 가져온 5가지 관점의 리포트를 '검토'하고 '승인'할 뿐입니다. 이를 통해 기획자는 단순 문서 작업에서 해방되어, 진짜 '가치 창출'과 '비즈니스 전략'에 더 많은 시간을 쏟을 수 있게 되었습니다.

앞으로 이 5명의 에이전트들이 실제 쇼피파이 프로젝트에서 어떻게 협력하는지, 구체적인 케이스 스터디로 다시 찾아오겠습니다.

Tony Lee (Eunjae Lee) Project Manager / Spec Owner GitHub: ej-rarus/spec-owner-kit

#AX #AI #ProductManagement #기획 #Shopify #Agile #SpecOwner #Claude

로그인 북마크렛 생성기 개발기 🔐

Thu, 11 Dec 2025 09:02:19 GMT

테스트 계정으로 반복 로그인하기 귀찮아서 만든 자동 로그인 도구

🎯 프로젝트 배경

웹 개발을 하다 보면 테스트 환경에서 여러 계정으로 로그인/로그아웃을 반복해야 할 때가 많습니다. 매번 아이디와 비밀번호를 입력하고 로그인 버튼을 누르는 작업이 생각보다 귀찮더라고요.

"북마크 하나로 자동 로그인되면 얼마나 편할까?" 라는 생각에서 시작된 프로젝트입니다.

목표

코딩 지식이 없는 사람도 쉽게 사용할 수 있어야 함
HTML만 업로드하면 자동으로 북마크렛 생성
여러 계정을 관리하기 쉬워야 함

🛠 기술 스택

순수 HTML/CSS/JavaScript - 별도의 프레임워크 없이 가볍게
브라우저 API - FileReader, DOMParser, iframe 활용
SheetJS (xlsx) - 엑셀 파일 파싱용

서버가 필요 없는 100% 클라이언트 사이드 애플리케이션으로 설계했습니다.

✨ 주요 기능

1. 자동 로그인 폼 감지

HTML 파일을 업로드하면 로그인 폼 요소를 자동으로 찾아냅니다.

function detectLoginFormElements(doc) {
    // 비밀번호 필드 먼저 찾기 (가장 확실한 요소)
    const passwordInput = doc.querySelector('input[type="password"]');

    // ID 필드 찾기 - name 속성 우선 검색
    const candidates = [
        'input[name="username"]',
        'input[name="user"]',
        'input[type="email"]',
        // ... 더 많은 패턴
    ];

    // 로그인 버튼 찾기
    const submitButton = doc.querySelector('button[type="submit"]');

    // ...
}

2. 시각적 요소 선택 기능

자동 감지가 실패할 때를 대비한 핵심 기능입니다. 사용자가 직접 눈으로 보고 클릭해서 요소를 선택할 수 있습니다.

개발 과정의 핵심 문제들

문제 1: iframe 하이라이트가 안 보임

원인: iframe 내부에 CSS가 주입되지 않음
해결: iframe 로드 완료 후 동적으로 스타일 주입

function injectStylesIntoIframe(iframe) {
    const iframeDoc = iframe.contentDocument;
    const style = iframeDoc.createElement('style');
    style.textContent = `
        .element-highlight {
            outline: 3px solid #4caf50 !important;
            outline-offset: 2px;
            background: rgba(76, 175, 80, 0.1) !important;
        }
    `;
    iframeDoc.head.appendChild(style);
}

문제 2: iframe이 프리즈되어 클릭이 안 됨

원인: 오버레이가 iframe 위를 덮어서 클릭 이벤트 차단
해결: pointer-events: none으로 오버레이는 클릭을 통과시키고, 가이드 박스만 클릭 가능하게 설정

.selection-overlay {
    pointer-events: none; /* iframe 클릭 허용 */
}

.selection-guide {
    pointer-events: auto; /* 가이드 박스는 클릭 가능 */
}

이 문제를 해결하는 데 가장 많은 시간이 걸렸는데, 해결하고 나니 정말 뿌듯했습니다! 🎉

문제 3: 이벤트 리스너가 불안정함

원인: 개별 요소에 이벤트를 붙이는 방식
해결: 이벤트 위임(Event Delegation) 방식으로 변경

// Before: 개별 요소마다 이벤트 추가 (불안정)
allElements.forEach(element => {
    element.addEventListener('click', handleClick);
});

// After: 부모에 하나의 리스너만 (안정적)
iframeDoc.body.addEventListener('click', function(e) {
    if (e.target.matches('input, button, a')) {
        handleElementSelection(e.target);
    }
}, true);

3. 북마크렛 코드 생성

선택된 요소 정보를 바탕으로 북마크렛을 생성합니다.

function createBookmarkletCode(account) {
    const code = `
(function() {
    const idInput = document.querySelector('${idSelector}');
    const pwInput = document.querySelector('${passwordSelector}');

    if (idInput) idInput.value = '${account.id}';
    if (pwInput) pwInput.value = '${account.password}';

    const btn = document.querySelector('${buttonSelector}');
    if (btn) btn.click();
})();
    `.trim();

    return `javascript:${encodeURIComponent(code)}`;
}

북마크 URL에 JavaScript 코드를 저장하는 방식입니다. javascript: 프로토콜을 사용하면 북마크 클릭 시 해당 코드가 실행됩니다.

4. 계정 관리

엑셀 업로드 방식

function handleExcelFile(file) {
    const reader = new FileReader();
    reader.onload = (e) => {
        const data = new Uint8Array(e.target.result);
        const workbook = XLSX.read(data, { type: 'array' });
        const firstSheet = workbook.Sheets[workbook.SheetNames[0]];
        const jsonData = XLSX.utils.sheet_to_json(firstSheet);

        // ID, Password 컬럼 자동 감지 (대소문자 무시)
        accountList = jsonData.map(row => {
            const idKey = Object.keys(row).find(key =>
                key.toLowerCase().includes('id') ||
                key.toLowerCase().includes('user')
            );
            // ...
        });
    };
}

수동 입력 방식

동적으로 행 추가/삭제 가능
실시간으로 계정 개수 표시

5. 북마크 등록 방법

생성된 북마크렛을 브라우저에 등록하는 세 가지 방법을 제공합니다.

방법 1: 드래그 앤 드롭 (가장 쉬움!)

HTML5 Drag and Drop API를 활용한 직관적인 방법입니다.


    📌 ${account.name}

사용자가 생성된 링크를 브라우저 북마크바로 드래그하기만 하면 자동으로 북마크가 등록됩니다. 별도의 복사/붙여넣기 과정이 필요 없어 가장 빠르고 편리한 방법입니다.

방법 2: HTML 파일 내보내기 (대량 등록)

여러 계정을 한 번에 등록할 때 유용한 방법입니다. Netscape Bookmark File Format을 사용해 브라우저가 인식할 수 있는 북마크 파일을 생성합니다.

function exportBookmarks() {
    let bookmarksHTML = `

Bookmarks
Bookmarks

    
로그인 북마크렛
    `;

    allAccounts.forEach(account => {
        const bookmarkletCode = createBookmarkletCode(account);
        const escapedName = account.name
            .replace(/&/g, '&')
            .replace(//g, '>')
            .replace(/"/g, '"');
        bookmarksHTML += `        
${escapedName}\n`;
    });

    bookmarksHTML += `    
\n`;

    // Blob으로 파일 생성 및 다운로드
    const blob = new Blob([bookmarksHTML], { type: 'text/html' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'login_bookmarklets.html';
    a.click();
}

Netscape Bookmark Format은 모든 주요 브라우저(Chrome, Firefox, Edge, Safari)에서 지원하는 표준 형식입니다. 생성된 HTML 파일을 브라우저의 "북마크 가져오기" 기능으로 불러오면 모든 북마크가 한 번에 등록됩니다.

방법 3: 코드 복사 (수동)

각 북마크렛의 코드를 복사해서 수동으로 북마크를 만드는 전통적인 방법입니다.

function copyBookmarkletCode(code, index) {
    navigator.clipboard.writeText(code).then(() => {
        showCopyFeedback(index);
    });
}

Clipboard API를 사용해 원클릭 복사를 구현했습니다.

6. UI 개선: 목록형 디자인

초기 버전의 카드 기반 UI에서 테이블 기반 목록형 UI로 전면 개편했습니다.

변경 배경

카드 UI는 계정이 많을 때 세로로 길어져서 스크롤이 많이 필요했음
정보 밀도가 낮아 한 화면에 적은 수의 북마크만 표시됨
드래그 앤 드롭 링크가 시각적으로 덜 돋보였음

새로운 테이블 UI

function generateBookmarklets() {
    resultsDiv.innerHTML = `
        
            
                
                    계정 정보
                    북마크 드래그
                    동작
                
            
            
        
    `;

    allAccounts.forEach((account, index) => {
        const row = tbody.insertRow();
        row.innerHTML = `
            
                ${account.name}
                ID: ${account.id}
            
            
                
                    📌 ${account.name}
                
            
            
                
            
        `;
    });
}

개선 효과

공간 효율성 300% 향상: 같은 화면 크기에 3배 이상의 북마크 표시
명확한 정보 계층: 계정 정보 → 드래그 링크 → 액션 버튼 순으로 시각적 흐름 개선
드래그 타겟 명확화: 📌 아이콘으로 드래그 가능한 요소를 직관적으로 표시

🎨 UX 개선 과정

사용자 피드백 반영

피드백 1: "HTML 파일 준비가 복잡해요"

기존: 페이지 소스 보기 → 복사 → 메모장에 붙여넣기 → 저장
개선: 로그인 페이지에서 Ctrl+S 누르기만 하면 끝!

튜토리얼에도 이 내용을 강조했습니다.

피드백 2: "코드를 모르는데 어떻게 요소를 선택하나요?"

이 피드백이 시각적 선택 기능을 만든 계기였습니다.

코드 대신 눈으로 보고 클릭
초록색 하이라이트로 시각적 피드백
잘못 선택하면 "↶ 이전 단계" 버튼으로 되돌리기

피드백 3: "FAQ 섹션이 디자인이 달라서 어색해요"

문제: h3 태그로 질문을 표시해서 다른 섹션과 스타일이 달랐음
해결: FAQ도 step-card로 감싸서 디자인 통일


Q1. 북마크렛이 작동하지 않아요
답변...



    Q1. 북마크렛이 작동하지 않아요
    답변...

피드백 4: "북마크를 어떻게 등록하나요?"

문제: 북마크렛 코드를 복사한 후 수동으로 북마크를 만드는 과정이 복잡했음
해결: 세 가지 등록 방법 제공
1. 드래그 앤 드롭 (가장 직관적)
2. HTML 파일 내보내기 (대량 등록)
3. 코드 복사 (전통적 방법)


    1
    
        🖱️ 드래그 앤 드롭 (가장 쉬움!)
        생성된 표에서 📌 계정 이름 링크를 브라우저 북마크바로 드래그

피드백 5: "카드 UI가 공간을 많이 차지해요"

문제: 계정이 10개만 되어도 스크롤이 너무 길어짐
해결: 테이블 기반 목록형 UI로 재설계
- 정보 밀도 3배 향상
- 한눈에 더 많은 북마크 확인 가능
- 드래그 타겟이 더 명확해짐

CSS 최적화

UI 개편과 함께 불필요한 스타일을 대폭 정리했습니다.

제거한 스타일:

.copy-btn (통합 복사 버튼)
.drag-handle (개별 드래그 핸들)
.result-item (카드 레이아웃)
.bookmarklet-card (카드 컴포넌트)

새로 추가한 스타일:

.bookmarklet-table {
    width: 100%;
    border-collapse: collapse;
    background: white;
    border-radius: 8px;
    overflow: hidden;
    box-shadow: 0 2px 8px rgba(0,0,0,0.1);
}

.method-section {
    display: flex;
    gap: 15px;
    padding: 20px;
    background: #f8f9fa;
    border-radius: 8px;
}

.method-number {
    flex-shrink: 0;
    width: 40px;
    height: 40px;
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    color: white;
    font-weight: bold;
    /* ... */
}

재사용 가능한 컴포넌트 중심으로 CSS를 재구성해 유지보수성을 크게 개선했습니다.

📱 반응형 디자인

데스크톱과 모바일 모두에서 사용 가능하도록 설계했습니다.

@media (max-width: 1024px) {
    .main-wrapper {
        flex-direction: column;
    }

    .sidebar {
        width: 100%;
        position: static;
    }

    .sidebar-menu {
        display: flex;
        flex-wrap: wrap;
        gap: 10px;
    }
}

🔒 보안 고려사항

클라이언트 사이드 처리

모든 데이터 처리는 브라우저 내부에서만 이루어짐
서버로 파일이나 계정 정보가 전송되지 않음
네트워크 요청 없이 완전히 오프라인에서도 작동 가능

주의사항 표시

⚠️ 주의사항
북마크렛에는 계정 정보가 평문으로 저장됩니다.
실제 프로덕션 계정이 아닌 테스트 계정에만 사용하세요!

튜토리얼에 경고 박스로 명확히 안내했습니다.

💡 배운 점

1. 사용자 중심 설계의 중요성

처음엔 "자동 감지만 잘 되면 되겠지"라고 생각했는데, 실제로는 다양한 로그인 폼 구조 때문에 감지가 실패하는 경우가 많았습니다. 시각적 선택 기능을 추가하면서 "기술이 완벽하지 않더라도, 사용자가 쉽게 대안을 선택할 수 있어야 한다"는 걸 배웠습니다.

2. iframe의 까다로움

iframe은 보안상의 이유로 많은 제약이 있습니다:

같은 origin이어야 접근 가능
sandbox 속성 설정 필요
스타일은 내부에 주입해야 함
이벤트는 위임 방식이 안정적

이런 제약들을 하나씩 해결하면서 iframe에 대한 이해도가 많이 높아졌습니다.

3. 점진적 개선

완벽한 결과물을 한 번에 만들려고 하지 않고:

기본 기능 구현 (자동 감지)
문제 발견 (감지 실패)
대안 추가 (시각적 선택)
UX 개선 (Ctrl+S, 이전 단계 버튼)
디자인 통일 (FAQ 스타일)
북마크 등록 간소화 (드래그 앤 드롭)
UI 재설계 (테이블 형식)
CSS 최적화

이렇게 단계적으로 개선해나가는 과정이 더 효과적이었습니다.

4. 브라우저 표준 API 활용

프레임워크 없이 순수 JavaScript만으로 구현하면서 다양한 브라우저 API를 활용했습니다:

HTML5 Drag and Drop API: 드래그 앤 드롭 구현
Blob API: 클라이언트 사이드에서 파일 생성 및 다운로드
Clipboard API: 원클릭 복사 기능
URL.createObjectURL(): 메모리 효율적인 파일 다운로드

특히 Netscape Bookmark Format을 발견한 것이 큰 도움이 되었습니다. 1990년대부터 사용된 오래된 표준이지만, 2025년 현재까지도 모든 주요 브라우저에서 지원하는 것을 보고 웹 표준의 힘을 다시 한번 느꼈습니다.

5. 정보 밀도와 사용성의 균형

카드 UI에서 테이블 UI로 변경하면서 배운 점:

더 많은 정보 ≠ 복잡함: 정보를 잘 정리하면 오히려 이해하기 쉬워짐
공간 효율성의 중요성: 스크롤을 줄이면 사용자 경험이 크게 개선됨
시각적 계층 구조: 테이블의 열 구조가 정보의 우선순위를 명확히 전달함

🎯 개선하고 싶은 점

완료된 기능 ✅

북마크 내보내기/가져오기 기능
- HTML 파일 내보내기 (Netscape Bookmark Format)
- 드래그 앤 드롭으로 즉시 등록
- 코드 복사 기능
UI 개선
- 목록형 테이블 디자인
- 정보 밀도 300% 향상
- 반응형 레이아웃

향후 계획

브라우저 확장 프로그램 버전
- 현재: 북마크렛 방식 (제한적)
- 목표: Chrome/Firefox 확장 프로그램으로 더 강력한 기능 제공
더 다양한 로그인 폼 패턴 지원
- reCAPTCHA 우회 방법 안내
- 2단계 인증 고려
- SPA(Single Page Application) 로그인 폼 지원
다국어 지원 (영어, 일본어 등)
- 현재: 한국어만 지원
- 목표: 글로벌 개발자들도 사용할 수 있게
북마크렛 테스트 기능
- 페이지 내에서 미리 북마크렛 동작 테스트
- 오류 디버깅 도구 제공
북마크 그룹 관리
- 프로젝트별/환경별로 북마크 그룹화
- 그룹 단위 내보내기/가져오기

📊 성과

주요 지표

순수 JavaScript로 구현 (프레임워크 없음, 의존성 최소화)
파일 크기: 약 50KB (압축되지 않은 상태에서도 가볍고 빠름)
서버 비용: $0 (정적 호스팅만 필요, GitHub Pages 무료 배포 가능)
지원 브라우저: Chrome, Firefox, Edge, Safari (모든 주요 브라우저)
오프라인 작동: 네트워크 연결 없이도 100% 사용 가능

기능 통계

계정 관리 방식: 2가지 (엑셀 업로드, 수동 입력)
북마크 등록 방법: 3가지 (드래그 앤 드롭, HTML 내보내기, 코드 복사)
폼 요소 감지: 자동 감지 + 시각적 수동 선택
지원 파일 형식: HTML, XLSX (Excel)

사용자 경험 개선

기존 방식 (수동 로그인):

HTML 파일 준비: 30초 (소스 보기 → 복사 → 붙여넣기 → 저장)
북마크 만들기: 60초 (북마크 추가 → 이름 입력 → URL 붙여넣기)
로그인 실행: 10초 (ID 입력 → 비밀번호 입력 → 버튼 클릭)

개선된 방식 (북마크렛):

HTML 파일 준비: 5초 (Ctrl+S)
북마크 만들기: 3초 (드래그 앤 드롭)
로그인 실행: 1초 (북마크 클릭 한 번)

전체 프로세스 시간 절약: 100초 → 9초 = 91% 시간 절약 🚀

UI 개선 효과

카드 UI (초기): 10개 계정 = 약 1800px 세로 높이
테이블 UI (개선): 10개 계정 = 약 600px 세로 높이
스크롤 감소: 67% ↓
정보 밀도: 300% ↑

🎉 마무리

처음엔 "간단한 도구"로 시작했지만, 실제로 만들어보니 예상보다 고려해야 할 것들이 많았습니다. 특히 코딩을 모르는 사용자도 쉽게 사용할 수 있게 만드는 과정에서 많은 것을 배웠습니다.

개발 과정에서 가장 기억에 남는 순간들

1. iframe 프리즈 문제 해결 pointer-events: none이라는 간단한 CSS 속성 하나로 해결되는 문제였지만, 그걸 찾기까지의 과정이 정말 값진 경험이었습니다. 몇 시간 동안 JavaScript 이벤트 처리 방법을 바꿔보고, z-index를 조정하고, 심지어 iframe을 다시 구현하려고까지 했는데, 결국 답은 CSS에 있었습니다.

2. 드래그 앤 드롭 구현의 즐거움 "북마크를 어떻게 쉽게 등록할까?" 고민하다가 드래그 앤 드롭을 떠올렸을 때의 짜릿함! HTML5 API만으로 이렇게 직관적인 UX를 만들 수 있다는 게 신기했습니다. 복잡한 프레임워크 없이도 충분히 모던한 인터페이스를 만들 수 있다는 자신감을 얻었습니다.

3. Netscape Bookmark Format 발견 "브라우저에 어떻게 자동으로 북마크를 추가하지?" 검색하다가 1990년대 포맷을 발견하고 놀랐습니다. 30년 전 표준이 2025년에도 모든 브라우저에서 작동한다는 사실이 웹 표준의 지속성을 보여주는 완벽한 예시였습니다.

4. UI 재설계 결정 카드 UI가 "예쁘긴 한데 실용적이지 않다"는 피드백을 받고 테이블로 전환했을 때, 처음엔 "디자인이 너무 평범해지는 거 아닌가?" 걱정했습니다. 하지만 완성하고 보니 기능이 곧 디자인이라는 걸 깨달았습니다. 사용자가 원하는 건 화려한 UI가 아니라 빠르고 명확한 UI였습니다.

핵심 교훈

이 프로젝트를 통해 "사용자가 쉽게 사용할 수 있는 도구"를 만드는 것이 "기술적으로 완벽한 도구"를 만드는 것보다 훨씬 중요하다는 걸 깨달았습니다.

자동 감지가 100% 작동하지 않아도 → 시각적 선택으로 대안 제공
코드를 복사/붙여넣기하기 번거로워도 → 드래그 앤 드롭으로 간소화
화려한 카드 디자인이 공간을 많이 차지해도 → 실용적인 테이블로 전환

완벽한 기술보다 사용자 친화적인 경험이 더 중요합니다.

🔗 링크

📝 기술 블로그 시리즈

이 프로젝트에서 배운 내용을 시리즈로 정리할 예정입니다:

로그인 북마크렛 생성기 개발기 ← 현재 글
iframe 다루기: pointer-events와 이벤트 위임
- iframe 내부 스타일 동적 주입
- pointer-events로 클릭 이벤트 제어
- 이벤트 위임 패턴의 장점
순수 JavaScript로 파일 업로드 구현하기
- FileReader API 활용
- Blob과 URL.createObjectURL()
- Clipboard API로 복사 기능 구현
드래그 앤 드롭과 브라우저 북마크 포맷
- HTML5 Drag and Drop API
- Netscape Bookmark Format 파싱
- 크로스 브라우저 호환성

Made with ❤️ by EJ Lee

이 프로젝트가 도움이 되셨나요? ⭐️ Star를 눌러주세요!

Mermaid 인터랙티브 가이드 개발기 🎨

Wed, 10 Dec 2025 07:48:27 GMT

배포 링크: https://mermaid-interactive-guide.vercel.app GitHub: Repository

🤔 왜 만들었나요?

회사에서 기획서나 문서를 작성할 때마다 다이어그램이 필요했습니다. PowerPoint로 그리자니 시간이 오래 걸리고, 수정할 때마다 일일이 박스를 움직여야 했죠.

그러던 중 Mermaid라는 도구를 알게 되었습니다. 텍스트 몇 줄이면 다이어그램이 완성되는 신기한 도구였어요! 하지만 주변 동료들은 "어려워 보인다", "배우기 힘들 것 같다"는 반응이었습니다.

"5분이면 누구나 배울 수 있다"는 걸 보여주고 싶어서 이 가이드를 만들게 되었습니다.

💡 핵심 아이디어

1. 인터랙티브 학습

단순히 보기만 하는 튜토리얼이 아니라, 직접 코드를 수정하고 결과를 바로 확인할 수 있도록 만들었습니다.

graph LR
    A[코드 수정] --> B[버튼 클릭] --> C[결과 확인]

각 레슨마다 "✏️ 직접 수정해보기" 버튼을 누르면 코드 에디터가 나타나고, 사용자가 직접 수정해볼 수 있습니다.

2. 단계별 학습

초보자도 따라올 수 있도록 13개의 단계로 나누었습니다:

Lesson 0-9: 기본 문법 (박스, 화살표, 방향, 분기 등)
Lesson 10: Claude AI와 연동하는 법
Lesson 11: 이미지로 저장하는 법
Lesson 12: 실무 활용 사례
Lesson 13: 완료!

3. Claude AI 연동 강조

가장 중요한 포인트는 "직접 그리지 마세요!"입니다.

Mermaid 문법을 외울 필요 없이, Claude한테 "○○○ 다이어그램 그려줘"라고 하면 몇 초만에 완성됩니다. 이 가이드의 목적은:

Mermaid가 무엇인지 이해하기
Claude가 만든 다이어그램을 읽고 수정할 수 있게 되기
실무에서 어떻게 활용할지 감 잡기

🛠️ 기술 스택

심플하게!

Mermaid.js v10 - 다이어그램 렌더링
Vanilla JavaScript - 인터랙티브 기능
CSS3 - 반응형 디자인 & 애니메이션
Vercel - 배포

프레임워크 없이 순수 HTML/CSS/JS로 만들었습니다. 가볍고 빠르게 동작하는 것이 목표였어요!

🎨 디자인 & UX

그라디언트와 애니메이션

보라색 그라디언트(#667eea → #764ba2)를 메인 컬러로 사용했습니다. 시각적으로 눈에 띄면서도 부담스럽지 않은 색상이에요.

background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);

"✏️ 직접 수정해보기" 버튼에는 펄스 애니메이션을 적용해서 "클릭해보세요!"라는 느낌을 주었습니다:

@keyframes pulse-button {
    0%, 100% {
        box-shadow: 0 4px 15px rgba(102, 126, 234, 0.4);
    }
    50% {
        box-shadow: 0 4px 25px rgba(102, 126, 234, 0.6);
        transform: scale(1.02);
    }
}

목차 네비게이션

오른쪽에 고정된 목차(TOC)를 만들어서 언제든지 원하는 레슨으로 점프할 수 있게 했습니다. 모바일에서는 자동으로 숨겨지고, 📑 버튼을 눌러서 열 수 있어요.

🚧 개발 과정에서 겪은 문제들

1. 다이어그램 렌더링 이슈

사용자가 코드를 수정하고 "🎨 그리기" 버튼을 누를 때, Mermaid가 제대로 렌더링되지 않는 문제가 있었습니다.

해결 방법: 기존 DOM을 완전히 제거하고 새로 만든 다음, mermaid.init()을 다시 호출했습니다.

function renderCode(lessonNum) {
    const code = document.getElementById('code-' + lessonNum).value;
    const preview = document.getElementById('preview-' + lessonNum);

    // 기존 내용 제거
    preview.innerHTML = '';

    // 임시 div 생성
    const tempDiv = document.createElement('div');
    tempDiv.innerHTML = '' + code + '';

    // preview에 추가
    preview.appendChild(tempDiv);

    // Mermaid 다시 초기화
    mermaid.init(undefined, tempDiv.querySelector('.mermaid'));
}

2. 다이어그램 크기 조절

사용자가 큰 다이어그램을 만들면 화면을 넘어가는 문제가 있었습니다.

해결 방법:

SVG의 max-width를 500px로 제한
스크롤이 가능하도록 overflow: auto 적용
모바일에서는 100% width로 자동 조절

.editor-container .preview-box svg {
    max-width: 500px !important;
    max-height: 500px !important;
    width: auto !important;
    height: auto !important;
}

3. SEO & 소셜 미디어 최적화

카카오톡이나 슬랙에 링크를 공유했을 때 예쁜 미리보기가 나오도록 Open Graph 메타 태그를 추가했습니다.

OG 이미지는 1792x1024 크기의 PNG 파일로 만들었어요!

📈 반복적인 개선

Git 커밋 히스토리를 보면 반복적으로 개선한 흔적이 보입니다:

첫 번째 버전: 기본 가이드 완성 (bf715f9)
시스템 아키텍처 추가 (dc4e49c)
Vercel 배포 URL 추가 (79e7c81)
"직접 해보세요" 버튼 강조 (c52623b) - 사용자가 인터랙티브 요소를 놓치지 않도록!
제작자 크레딧 추가 (e840a79)
다이어그램 오버플로우 수정 (ca1c152, 77063d8, ...)
SVG 크기 조절 (ea1319f, b841265, ...)
재시작 버튼 추가 (3131110)
Favicon & 소셜 미디어 태그 (6e393f8)
OG 이미지 업데이트 (0ce030c)

특히 다이어그램 크기 문제는 여러 번 커밋을 거쳐 해결했습니다. 사용자 경험을 위해 계속 테스트하고 개선했어요!

🎯 타겟 사용자

이 가이드는 다음 분들을 위해 만들었습니다:

📝 기획자: 기획서에 플로우차트를 추가하고 싶은데 어떻게 해야 할지 모르는 분
💻 개발자: API 플로우나 시스템 구조를 설명해야 하는데 PPT 그리기 귀찮은 분
📊 PM: 프로젝트 프로세스를 시각화하고 싶은 분
🎓 다이어그램 툴 입문자: 처음 배우는 모든 분

💪 실무 활용 예시

가이드에서 소개한 실무 활용 사례입니다:

1. 기획자: 좋아요 버튼 클릭 플로우

graph LR
    Click[좋아요 버튼 클릭] --> Check{로그인
했나요?}
    Check -->|아니오| Login[로그인 화면]
    Check -->|예| Like[하트 빨강게 변함]
    Like --> Count[숫자 1 증가]

2. 개발자: 코드 수정 & 배포 프로세스

graph LR
    Code[코드 수정] --> Test[내 컴퓨터에서 테스트]
    Test --> Push[GitHub에 올리기]
    Push --> Review[팀장님 확인]
    Review --> Deploy[서버에 배포]

3. PM: 고객 문의 처리

graph TD
    Start([문의 접수]) --> Type{문의 유형?}
    Type -->|배송 문의| Ship[배송팀에 전달]
    Type -->|환불 요청| Refund[환불 처리]
    Type -->|상품 문의| Answer[답변 작성]

    Ship --> Done([완료])
    Refund --> Done
    Answer --> Done

🚀 배포

Vercel로 배포했습니다. 설정이 거의 필요 없고, Git push만 하면 자동으로 배포되어서 정말 편리했어요!

배포 과정:

GitHub에 레포 push
Vercel에서 "New Project" 클릭
GitHub 레포 선택
Deploy 버튼 클릭
완료! 🎉

커스텀 도메인도 쉽게 연결할 수 있지만, 일단 Vercel 도메인(mermaid-interactive-guide.vercel.app)을 사용하고 있습니다.

📊 성과 & 피드백

목표 달성

✅ 5분만에 Mermaid 기본 문법 이해
✅ Claude AI와 연동하는 법 학습
✅ 실무 활용 방법 습득
✅ 인터랙티브하게 직접 수정하며 배우기

앞으로의 계획

더 많은 다이어그램 타입 추가 (시퀀스 다이어그램, 클래스 다이어그램 등)
실전 예제 더 추가
다국어 지원 (영문 버전)
사용자 피드백 수집 & 개선

🎓 배운 점

1. 단순함의 힘

프레임워크 없이 Vanilla JS로 만들었지만, 충분히 인터랙티브하고 반응성 있는 웹사이트를 만들 수 있었습니다. 때로는 단순한 것이 더 강력합니다!

2. 사용자 경험이 최우선

다이어그램 크기, 버튼 애니메이션, 목차 네비게이션 등 작은 디테일이 사용자 경험을 크게 바꿉니다. 커밋 히스토리를 보면 사용자 경험 개선에 많은 시간을 투자했다는 걸 알 수 있어요.

3. 반복적인 개선의 중요성

첫 번째 버전은 완벽하지 않았습니다. 하지만 계속 테스트하고 개선하면서 점점 나아졌어요. "완벽해질 때까지 기다리지 말고, 일단 만들고 개선하자!"

4. 메타 태그의 중요성

OG 이미지와 메타 태그를 추가하니 링크를 공유했을 때 훨씬 전문적으로 보였습니다. SEO와 소셜 미디어 최적화는 정말 중요해요!

🙏 마치며

처음에는 "동료들에게 Mermaid를 알려주고 싶다"는 단순한 목표로 시작했지만, 만들면서 많은 걸 배웠습니다.

특히 "사용자가 직접 수정하며 배우는 것"의 중요성을 깨달았어요. 단순히 보는 것과 직접 해보는 것은 완전히 다릅니다!

이 가이드가 더 많은 분들에게 Mermaid의 편리함을 알리는 계기가 되었으면 좋겠습니다 🎉

배포 링크: https://mermaid-interactive-guide.vercel.app

질문이나 피드백은 언제든지 환영합니다! 슬랙 @루쿠쿠 이은재 Tony로 연락주세요 🙌

Happy Diagramming! 🎨✨

Shopify 스토어 대시보드 만들기: 여러 API를 한 번에 조회하고 데이터 시각화하기

Mon, 08 Dec 2025 03:50:47 GMT

제품, 주문 등 여러 데이터를 동시에 가져와 스토어 현황을 한눈에 보여주는 대시보드를 구현합니다.

들어가며

실제 비즈니스에서 가장 중요한 것은 현황 파악입니다. 제품이 몇 개나 있고, 주문은 얼마나 들어왔고, 매출은 얼마인지 한눈에 볼 수 있어야 합니다.

이전 포스트에서 제품 목록 페이지를 만들었다면, 이번에는 한 단계 더 나아가 여러 데이터를 통합해서 보여주는 대시보드를 만들어보겠습니다.

완성 미리보기

┌─────────────────────────────────────────────────────┐
│  스토어 대시보드                                        ![](https://velog.velcdn.com/images/ej-rarus/post/02ae66e2-5371-4d44-977f-a425172772c3/image.png)
│
├─────────────────────────────────────────────────────┤
│  My Store                                           │
│  store@example.com  •  플랜: Basic Shopify           │
│                                                     │
│  ┌─────────────┬─────────────┬─────────────┐        │
│  │  총 제품 수   │  총 주문 수    │  총 매출     │        │
│  │     25      │     143     │KRW 4,250,000│        │
│  └─────────────┴─────────────┴─────────────┘        │
│                                                     │
│  최근 주문                                            │
│  ┌─────────────────────────────────────────┐        │
│  │ #1043  •  2025년 12월 8일                 │        │
│  │ KRW 89,000  •  결제 완료                   │        │
│  └─────────────────────────────────────────┘        │
│  ...                                                │
│                                                     │
│  [사이드바]                                           │
│  재고 부족 알림                                        │
│  • Red T-Shirt (재고: 5개)                            │
│  • Blue Cap (재고: 3개)                               │
└─────────────────────────────────────────────────────┘

1. 대시보드란?

대시보드의 목적

대시보드(Dashboard)는 여러 데이터를 한 화면에 모아서 보여주는 페이지입니다.

일반 페이지 vs 대시보드:

제품 목록 페이지:
- 1개의 API 호출 (products)
- 1가지 데이터 표시 (제품)

대시보드:
- 여러 API 동시 호출 (products, orders, shop)
- 여러 데이터 통합 표시 (통계, 차트, 알림)
- 데이터 가공 (합계, 평균, 필터링)

우리가 만들 대시보드

표시할 정보:

스토어 정보: 이름, 이메일, 플랜
주요 지표 카드: 총 제품 수, 총 주문 수, 총 매출
최근 주문: 최근 5개 주문 내역
재고 부족 알림: 재고 10개 미만 제품

2. 파일 생성 및 타입 정의

파일 생성

app/routes/app.dashboard.tsx 파일을 생성합니다.

TypeScript 타입 정의

import type { LoaderFunctionArgs } from "react-router";
import { useLoaderData } from "react-router";
import { authenticate } from "../shopify.server";

interface DashboardData {
  shop: {
    name: string;
    email: string;
    currencyCode: string;
    plan: {
      displayName: string;
    };
  };
  productsCount: number;
  ordersCount: number;
  totalSales: string;
  recentOrders: Array<{
    id: string;
    name: string;
    createdAt: string;
    currentTotalPrice: string;
    displayFinancialStatus: string;
  }>;
  lowStockProducts: Array<{
    id: string;
    title: string;
    totalInventory: number;
  }>;
}

포인트: 여러 종류의 데이터를 하나의 인터페이스로 정의합니다.

3. Loader 함수: 여러 API 동시 호출

대시보드의 핵심은 여러 데이터를 효율적으로 가져오는 것입니다.

전체 구조

export const loader = async ({ request }: LoaderFunctionArgs) => {
  const { admin } = await authenticate.admin(request);

  // ① 스토어 정보 조회
  const shopResponse = await admin.graphql(`...`);

  // ② 제품 목록 조회
  const productsResponse = await admin.graphql(`...`);

  // ③ 주문 목록 조회
  const ordersResponse = await admin.graphql(`...`);

  // ④ 데이터 파싱 및 가공
  const shopData = await shopResponse.json();
  const productsData = await productsResponse.json();
  const ordersData = await ordersResponse.json();

  // ⑤ 통계 계산 및 반환
  return {
    shop: shopData.data.shop,
    productsCount: products.length,
    ordersCount: orders.length,
    totalSales: calculateTotalSales(orders),
    recentOrders: getRecentOrders(orders, 5),
    lowStockProducts: getLowStockProducts(products, 10),
  };
};

① 스토어 정보 조회

const shopResponse = await admin.graphql(
  `#graphql
    query getShopInfo {
      shop {
        name
        email
        currencyCode
        plan {
          displayName
        }
      }
    }
  `
);
const shopData = await shopResponse.json();

가져오는 정보:

name: 스토어명
email: 스토어 이메일
currencyCode: 통화 코드 (KRW, USD 등)
plan.displayName: 요금제 (Basic, Shopify, Advanced 등)

② 제품 목록 조회

const productsResponse = await admin.graphql(
  `#graphql
    query getProducts {
      products(first: 250) {
        edges {
          node {
            id
            title
            totalInventory
          }
        }
      }
    }
  `
);
const productsData = await productsResponse.json();
const products = productsData.data?.products?.edges.map((edge: any) => edge.node) || [];

왜 250개?

Shopify GraphQL은 한 번에 최대 250개까지 조회 가능
더 많은 데이터는 페이지네이션 필요

③ 주문 목록 조회

const ordersResponse = await admin.graphql(
  `#graphql
    query getOrders {
      orders(first: 250) {
        edges {
          node {
            id
            name
            createdAt
            currentTotalPriceSet {
              shopMoney {
                amount
                currencyCode
              }
            }
            displayFinancialStatus
          }
        }
      }
    }
  `
);
const ordersData = await ordersResponse.json();
const orders = ordersData.data?.orders?.edges.map((edge: any) => edge.node) || [];

주요 필드:

name: 주문 번호 (#1001)
createdAt: 주문 일시
currentTotalPriceSet: 주문 금액 (통화 포함)
displayFinancialStatus: 결제 상태 (PAID, PENDING, REFUNDED 등)

4. 데이터 가공 및 계산

조회한 데이터를 대시보드에 맞게 가공합니다.

총 매출 계산

const totalSales = orders.reduce((sum: number, order: any) => {
  return sum + parseFloat(order.currentTotalPriceSet?.shopMoney?.amount || "0");
}, 0);

동작 원리:

// orders 배열
[
  { amount: "50000" },
  { amount: "30000" },
  { amount: "20000" }
]

// reduce 계산
0 + 50000 = 50000
50000 + 30000 = 80000
80000 + 20000 = 100000

// 결과: 100000

최근 주문 추출

const recentOrders = orders
  .slice(0, 5)  // 처음 5개만
  .map((order: any) => ({
    id: order.id,
    name: order.name,
    createdAt: order.createdAt,
    currentTotalPrice: order.currentTotalPriceSet?.shopMoney?.amount || "0",
    displayFinancialStatus: order.displayFinancialStatus,
  }));

slice(0, 5): 배열의 처음 5개 요소만 선택

재고 부족 제품 필터링

const lowStockProducts = products
  .filter((p: any) => p.totalInventory > 0 && p.totalInventory < 10)
  .slice(0, 5)
  .map((p: any) => ({
    id: p.id,
    title: p.title,
    totalInventory: p.totalInventory,
  }));

로직:

filter: 재고가 1~9개인 제품만 선택
slice(0, 5): 최대 5개만
map: 필요한 필드만 추출

5. UI 컴포넌트: 카드와 통계

대시보드는 시각적으로 정보를 전달해야 합니다.

스토어 정보 섹션


  
    {data.shop.name}
    
      
        {data.shop.email}
      
      
        플랜: {data.shop.plan?.displayName}

주요 지표 카드 (3개)


  
    {/* 제품 수 카드 */}
    
      
        
          {data.productsCount}
        
        
          총 제품 수
        
      
    

    {/* 주문 수 카드 */}
    
      
        
          {data.ordersCount}
        
        
          총 주문 수
        
      
    

    {/* 매출 카드 */}
    
      
        
          {formatCurrency(data.totalSales)}
        
        
          총 매출

핵심 스타일링:

direction="inline": 가로로 나열
style={{ flex: 1 }}: 동일한 너비로 분할
variant="heading-2xl": 큰 숫자 강조

최근 주문 목록


  {data.recentOrders.length === 0 ? (
    주문이 없습니다.
  ) : (
    
      {data.recentOrders.map((order) => (
        
          
            
              
                {order.name}
              
              
                {formatDate(order.createdAt)}
              
            
            
              
                {formatCurrency(order.currentTotalPrice)}
              
              
                {order.displayFinancialStatus === "PAID"
                  ? "결제 완료"
                  : order.displayFinancialStatus === "PENDING"
                  ? "결제 대기"
                  : order.displayFinancialStatus}
              
            
          
        
      ))}
    
  )}

조건부 색상:

tone="success": 결제 완료 시 녹색
tone="subdued": 그 외 회색

재고 부족 알림 (사이드바)


  {data.lowStockProducts.length === 0 ? (
    재고 부족 제품이 없습니다.
  ) : (
    
      {data.lowStockProducts.map((product) => (
        
          
            
              {product.title}
            
            
              재고: {product.totalInventory}개
            
          
        
      ))}
    
  )}

slot="aside": Polaris의 사이드바 슬롯에 배치

tone="critical": 빨간색 강조 (경고)

6. 유틸리티 함수

데이터를 보기 좋게 포맷팅하는 함수들입니다.

날짜 포맷팅

const formatDate = (dateString: string) => {
  const date = new Date(dateString);
  return new Intl.DateTimeFormat("ko-KR", {
    year: "numeric",
    month: "long",
    day: "numeric",
    hour: "2-digit",
    minute: "2-digit",
  }).format(date);
};

// 사용 예
formatDate("2025-12-08T10:30:00Z")
// → "2025년 12월 8일 오전 10:30"

통화 포맷팅

const formatCurrency = (amount: string) => {
  return `${data.shop.currencyCode} ${Number(amount).toLocaleString()}`;
};

// 사용 예
formatCurrency("1234567")
// → "KRW 1,234,567"

toLocaleString(): 천 단위 구분 기호 자동 추가

7. 권한 설정

주문 데이터를 조회하려면 권한이 필요합니다.

`shopify.app.toml` 수정

[access_scopes]
scopes = "write_products,read_orders"

필요한 권한:

write_products: 제품 조회 (이미 있음)
read_orders: 주문 조회 (추가 필요)

서버 재시작

# 기존 서버 종료 (Ctrl+C)
npm run dev

개발 모드에서는 자동으로 권한 승인됩니다!

8. Protected Customer Data 이슈

문제 발생

처음에 고객 데이터까지 표시하려고 했지만:

// ❌ 에러 발생!
const customersResponse = await admin.graphql(`
  query {
    customers(first: 10) {
      edges {
        node {
          id
          email
          firstName
        }
      }
    }
  }
`);

// Error: This app is not approved to access the Customer object.

이유

Shopify는 고객 개인정보 보호를 위해 특별한 승인 절차가 필요합니다:

개인정보 보호 정책 제출
앱 심사 및 승인
Shopify의 승인 대기

개발 단계에서는 접근 불가!

해결책

대시보드에서 고객 수 카드를 제거하고, 주문의 고객 이름도 표시하지 않습니다:

// ✅ 고객 데이터 없이도 충분히 유용한 대시보드
return {
  shop: shopData.data.shop,
  productsCount: products.length,
  ordersCount: orders.length,
  totalSales: totalSales.toFixed(2),
  recentOrders,  // 고객 이름 제외
  lowStockProducts,
};

9. 네비게이션 추가

`app/routes/app.tsx` 수정


  Home
  대시보드  {/* ← 추가 */}
  제품 목록

10. 완성 코드

전체 파일

app/routes/app.dashboard.tsx:

import type { LoaderFunctionArgs } from "react-router";
import { useLoaderData } from "react-router";
import { authenticate } from "../shopify.server";

interface DashboardData {
  shop: {
    name: string;
    email: string;
    currencyCode: string;
    plan: {
      displayName: string;
    };
  };
  productsCount: number;
  ordersCount: number;
  totalSales: string;
  recentOrders: Array<{
    id: string;
    name: string;
    createdAt: string;
    currentTotalPrice: string;
    displayFinancialStatus: string;
  }>;
  lowStockProducts: Array<{
    id: string;
    title: string;
    totalInventory: number;
  }>;
}

export const loader = async ({ request }: LoaderFunctionArgs) => {
  const { admin } = await authenticate.admin(request);

  // 스토어 정보
  const shopResponse = await admin.graphql(
    `#graphql
      query getShopInfo {
        shop {
          name
          email
          currencyCode
          plan {
            displayName
          }
        }
      }
    `
  );
  const shopData = await shopResponse.json();

  // 제품 통계
  const productsResponse = await admin.graphql(
    `#graphql
      query getProducts {
        products(first: 250) {
          edges {
            node {
              id
              title
              totalInventory
            }
          }
        }
      }
    `
  );
  const productsData = await productsResponse.json();
  const products = productsData.data?.products?.edges.map((edge: any) => edge.node) || [];

  // 주문 통계
  const ordersResponse = await admin.graphql(
    `#graphql
      query getOrders {
        orders(first: 250) {
          edges {
            node {
              id
              name
              createdAt
              currentTotalPriceSet {
                shopMoney {
                  amount
                  currencyCode
                }
              }
              displayFinancialStatus
            }
          }
        }
      }
    `
  );
  const ordersData = await ordersResponse.json();
  const orders = ordersData.data?.orders?.edges.map((edge: any) => edge.node) || [];

  // 데이터 가공
  const totalSales = orders.reduce((sum: number, order: any) => {
    return sum + parseFloat(order.currentTotalPriceSet?.shopMoney?.amount || "0");
  }, 0);

  const recentOrders = orders
    .slice(0, 5)
    .map((order: any) => ({
      id: order.id,
      name: order.name,
      createdAt: order.createdAt,
      currentTotalPrice: order.currentTotalPriceSet?.shopMoney?.amount || "0",
      displayFinancialStatus: order.displayFinancialStatus,
    }));

  const lowStockProducts = products
    .filter((p: any) => p.totalInventory > 0 && p.totalInventory < 10)
    .slice(0, 5)
    .map((p: any) => ({
      id: p.id,
      title: p.title,
      totalInventory: p.totalInventory,
    }));

  return {
    shop: shopData.data?.shop || {},
    productsCount: products.length,
    ordersCount: orders.length,
    totalSales: totalSales.toFixed(2),
    recentOrders,
    lowStockProducts,
  };
};

export default function DashboardPage() {
  const data = useLoaderData();

  const formatDate = (dateString: string) => {
    const date = new Date(dateString);
    return new Intl.DateTimeFormat("ko-KR", {
      year: "numeric",
      month: "long",
      day: "numeric",
      hour: "2-digit",
      minute: "2-digit",
    }).format(date);
  };

  const formatCurrency = (amount: string) => {
    return `${data.shop.currencyCode} ${Number(amount).toLocaleString()}`;
  };

  return (
    
      {/* 스토어 정보 */}
      
        
          {data.shop.name}
          
            
              {data.shop.email}
            
            
              플랜: {data.shop.plan?.displayName}
            
          
        
      

      {/* 주요 지표 */}
      
        
          
            
              
                {data.productsCount}
              
              
                총 제품 수
              
            
          

          
            
              
                {data.ordersCount}
              
              
                총 주문 수
              
            
          

          
            
              
                {formatCurrency(data.totalSales)}
              
              
                총 매출
              
            
          
        
      

      {/* 최근 주문 */}
      
        {data.recentOrders.length === 0 ? (
          주문이 없습니다.
        ) : (
          
            {data.recentOrders.map((order) => (
              
                
                  
                    
                      {order.name}
                    
                    
                      {formatDate(order.createdAt)}
                    
                  
                  
                    
                      {formatCurrency(order.currentTotalPrice)}
                    
                    
                      {order.displayFinancialStatus === "PAID"
                        ? "결제 완료"
                        : order.displayFinancialStatus === "PENDING"
                        ? "결제 대기"
                        : order.displayFinancialStatus}
                    
                  
                
              
            ))}
          
        )}
      

      {/* 재고 부족 제품 */}
      
        {data.lowStockProducts.length === 0 ? (
          재고 부족 제품이 없습니다.
        ) : (
          
            {data.lowStockProducts.map((product) => (
              
                
                  
                    {product.title}
                  
                  
                    재고: {product.totalInventory}개
                  
                
              
            ))}
          
        )}
      

      {/* 안내 */}
      
        
          이 대시보드는 스토어의 주요 지표를 실시간으로 표시합니다.
        
        
          제품, 주문 통계
          최근 5개 주문 내역
          재고 10개 미만 제품 알림
        
        
          참고: 고객 데이터는 Shopify의 보호된 데이터 정책으로 인해 표시되지 않습니다.
        
      
    
  );
}

11. 확장 아이디어

일별 매출 차트

// Chart.js 또는 Recharts 라이브러리 사용
const salesByDate = orders.reduce((acc, order) => {
  const date = order.createdAt.split('T')[0];
  acc[date] = (acc[date] || 0) + parseFloat(order.currentTotalPrice);
  return acc;
}, {});

베스트셀러 TOP 5

주문의 lineItems를 분석해서 가장 많이 팔린 제품 추출:

const bestSellers = lineItems
  .reduce((acc, item) => {
    acc[item.productId] = (acc[item.productId] || 0) + item.quantity;
    return acc;
  }, {})
  .sort((a, b) => b.quantity - a.quantity)
  .slice(0, 5);

실시간 업데이트

useEffect(() => {
  const interval = setInterval(() => {
    revalidate();  // React Router의 revalidate 사용
  }, 30000);  // 30초마다 갱신

  return () => clearInterval(interval);
}, []);

기간 선택 필터

const [period, setPeriod] = useState('week'); // week, month, year

const filteredOrders = orders.filter(order => {
  const orderDate = new Date(order.createdAt);
  const now = new Date();
  const diff = now - orderDate;

  if (period === 'week') return diff < 7 * 24 * 60 * 60 * 1000;
  if (period === 'month') return diff < 30 * 24 * 60 * 60 * 1000;
  return true;
});

12. 핵심 개념 정리

여러 API 병렬 호출

// ✅ 좋은 예: 순차 호출 (하나씩)
const shop = await admin.graphql(`query { shop {...} }`);
const products = await admin.graphql(`query { products {...} }`);
const orders = await admin.graphql(`query { orders {...} }`);

// 총 시간: T1 + T2 + T3

// ⚠️ 더 좋은 예: 병렬 호출 (동시에)
const [shopRes, productsRes, ordersRes] = await Promise.all([
  admin.graphql(`query { shop {...} }`),
  admin.graphql(`query { products {...} }`),
  admin.graphql(`query { orders {...} }`)
]);

// 총 시간: max(T1, T2, T3)

현재 코드는 순차 호출이지만, Promise.all을 사용하면 더 빠르게 개선 가능!

Array 메서드 활용

// filter: 조건에 맞는 항목 선택
products.filter(p => p.inventory < 10)

// map: 각 항목 변환
products.map(p => ({ id: p.id, name: p.title }))

// reduce: 합계 계산
orders.reduce((sum, order) => sum + order.price, 0)

// slice: 일부만 선택
orders.slice(0, 5)  // 처음 5개

데이터 가공의 중요성

원시 데이터 (Raw Data)
    ↓ filter, map, reduce
가공된 데이터 (Processed Data)
    ↓ formatCurrency, formatDate
표시용 데이터 (Display Data)

마치며

축하합니다! 스토어 대시보드를 완성했습니다! 🎉

이 대시보드를 만들면서:

✅ 여러 API를 한 번에 호출하는 방법을 배웠습니다 ✅ 데이터를 가공하고 계산하는 로직을 구현했습니다 ✅ 카드 형태의 통계 UI를 만들었습니다 ✅ 조건부 스타일링으로 상태를 시각적으로 표현했습니다 ✅ Protected Customer Data 이슈를 처리했습니다

제품 목록 페이지는 단순 조회였다면, 대시보드는 여러 데이터를 통합하고 가공하는 한 단계 높은 수준의 기능입니다.

다음 단계로는:

차트 라이브러리로 시각화 강화
기간별 필터링 기능
실시간 업데이트
데이터 내보내기 (CSV, Excel)

실전 비즈니스에서 가장 중요한 것은 데이터를 얼마나 잘 보여주느냐입니다. 이 대시보드가 그 시작점이 될 것입니다!

시리즈 글:

GitHub 저장소: https://github.com/ej-rarus/integrated-projection-app

질문이나 피드백은 댓글로 남겨주세요! 💬

Shopify API로 제품 목록 페이지 만들기: 첫 번째 실전 기능 구현

Mon, 08 Dec 2025 03:26:11 GMT

Shopify Admin GraphQL API를 활용해 실제 스토어 데이터를 조회하고 화면에 표시하는 방법을 단계별로 알아봅니다.

들어가며

이전 포스트에서 Shopify 커스텀 앱의 기본 구조와 API 사용법을 배웠습니다. 이제는 실제로 스토어 데이터를 다루는 기능을 만들어볼 차례입니다.

첫 번째 실전 프로젝트로 제품 목록 페이지를 만들어보겠습니다. 이 페이지는:

스토어의 모든 제품을 조회하고
제품 이미지, 이름, 가격, 재고를 표시하며
Shopify 스타일의 깔끔한 UI로 구현됩니다

완성 미리보기

이 튜토리얼을 마치면 다음과 같은 페이지가 만들어집니다:

┌─────────────────────────────────────────────────┐
│  제품 목록                                        │
├─────────────────────────────────────────────────┤
│  총 25개의 제품                                    │
│                                                 │
│  ┌─────────────────────────────────────────┐    │
│  │ [이미지]  Red Snowboard                   │    │
│  │          가격: ₩100,000  재고: 50개        │    │
│  │          상태: 활성                       │    │
│  └─────────────────────────────────────────┘    │
│                                                 │
│  ┌─────────────────────────────────────────┐    │
│  │ [이미지]  Blue T-Shirt                    │    │
│  │          가격: ₩29,000  재고: 100개        │    │
│  │          상태: 활성                        │   │
│  │                                         │    │
│  └─────────────────────────────────────────┘    │
│                                                 │
│  ...                                            │
└─────────────────────────────────────────────────┘

1. 새 페이지 파일 생성

React Router는 파일명이 곧 URL입니다.

파일 생성

app/routes/app.products.tsx 파일을 생성합니다:

app/routes/
├── app.tsx              # 레이아웃 (이미 있음)
├── app._index.tsx       # Home (이미 있음)
└── app.products.tsx     # ← 새로 생성!

URL: /app/products

2. TypeScript 타입 정의

먼저 제품 데이터의 타입을 정의합니다:

// app/routes/app.products.tsx

import type { LoaderFunctionArgs } from "react-router";
import { useLoaderData } from "react-router";
import { authenticate } from "../shopify.server";

// 제품 데이터 타입 정의
interface Product {
  id: string;
  title: string;
  status: string;
  totalInventory: number;
  featuredImage?: {
    url: string;
  };
  variants: {
    edges: Array<{
      node: {
        price: string;
      };
    }>;
  };
}

// Loader가 반환하는 데이터 타입
interface LoaderData {
  products: Product[];
}

왜 타입을 정의하나요?

TypeScript의 자동완성 지원
런타임 에러 방지
코드 가독성 향상

3. Loader 함수: 데이터 가져오기

React Router의 Loader는 페이지 로드 시 서버에서 데이터를 가져오는 함수입니다.

전체 코드

export const loader = async ({ request }: LoaderFunctionArgs) => {
  // ① 인증된 admin 객체 가져오기
  const { admin } = await authenticate.admin(request);

  // ② Shopify GraphQL API로 제품 목록 가져오기
  const response = await admin.graphql(
    `#graphql
      query getProducts {
        products(first: 50) {
          edges {
            node {
              id
              title
              status
              totalInventory
              featuredImage {
                url
              }
              variants(first: 1) {
                edges {
                  node {
                    price
                  }
                }
              }
            }
          }
        }
      }
    `
  );

  // ③ 응답을 JSON으로 파싱
  const responseJson = await response.json();

  // ④ GraphQL의 edges 구조에서 실제 데이터 추출
  const products = responseJson.data?.products?.edges.map((edge: any) => edge.node) || [];

  // ⑤ 컴포넌트로 데이터 전달
  return { products };
};

단계별 설명

① 인증 객체 가져오기

const { admin } = await authenticate.admin(request);

authenticate.admin(request): 현재 세션 검증
admin: Shopify API 호출을 위한 클라이언트
인증 실패 시 자동으로 로그인 페이지로 리다이렉트

② GraphQL 쿼리 작성

query getProducts {
  products(first: 50) {        # 제품 50개 가져오기
    edges {                    # GraphQL 페이지네이션 구조
      node {                   # 실제 제품 데이터
        id                     # 제품 ID
        title                  # 제품명
        status                 # 상태 (ACTIVE, DRAFT, ARCHIVED)
        totalInventory         # 총 재고
        featuredImage {        # 대표 이미지
          url
        }
        variants(first: 1) {   # 첫 번째 변형 (가격 가져오기용)
          edges {
            node {
              price
            }
          }
        }
      }
    }
  }
}

필드 선택 이유:

id: 각 제품의 고유 식별자 (React key로 사용)
title: 화면에 표시할 제품명
status: 활성/비활성 상태 표시
totalInventory: 재고 수량
featuredImage: 썸네일 이미지
variants[0].price: 기본 가격 (첫 번째 변형의 가격)

③ JSON 파싱

const responseJson = await response.json();

GraphQL 응답은 다음과 같은 구조입니다:

{
  "data": {
    "products": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/Product/123",
            "title": "Red Snowboard",
            "status": "ACTIVE",
            "totalInventory": 50,
            "featuredImage": {
              "url": "https://cdn.shopify.com/..."
            },
            "variants": {
              "edges": [
                {
                  "node": {
                    "price": "100.00"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

④ 데이터 추출

const products = responseJson.data?.products?.edges.map((edge: any) => edge.node) || [];

GraphQL의 edges 구조를 평탄화:

// 변환 전
[
  { node: { id: "123", title: "Product A" } },
  { node: { id: "456", title: "Product B" } }
]

// 변환 후
[
  { id: "123", title: "Product A" },
  { id: "456", title: "Product B" }
]

4. UI 컴포넌트: 제품 목록 표시

이제 가져온 데이터를 화면에 보여주는 컴포넌트를 만듭니다.

전체 코드

export default function ProductsPage() {
  // Loader에서 반환한 데이터 가져오기
  const { products } = useLoaderData();

  return (
    
      
        {/* 제품이 없을 때 */}
        {products.length === 0 ? (
          
            제품이 없습니다. Shopify Admin에서 제품을 추가해보세요!
          
        ) : (
          /* 제품이 있을 때 */
          
            
              총 {products.length}개의 제품
            
            
              {products.map((product) => (
                
                  
                    {/* 제품 이미지 */}
                    {product.featuredImage && (
                      
                    )}

                    {/* 제품 정보 */}
                    
                      
                        {product.title}
                      
                      
                        
                          가격:{" "}
                          {product.variants.edges[0]?.node.price
                            ? `₩${Number(product.variants.edges[0].node.price).toLocaleString()}`
                            : "가격 없음"}
                        
                        
                          재고: {product.totalInventory}개
                        
                        
                          상태:{" "}
                          {product.status === "ACTIVE" ? "활성" : "비활성"}
                        
                      
                    
                  
                
              ))}
            
          
        )}
      

      {/* 사이드바 안내 */}
      
        
          이 페이지는 Shopify Admin GraphQL API를 사용하여 스토어의 제품 목록을 가져옵니다.
        
        
          제품을 추가하려면 Shopify Admin → 제품 메뉴에서 추가하세요.
        
      
    
  );
}

컴포넌트 분석

Polaris Web Components

Shopify 스타일의 UI를 만들기 위해 태그를 사용합니다:

        {/* 페이지 컨테이너 */}
                         {/* 섹션 */}
         {/* 세로 스택 */}
              {/* 카드 박스 */}
          {/* 텍스트 */}

조건부 렌더링

{products.length === 0 ? (
  제품이 없습니다
) : (
  
    {/* 제품 목록 */}
  
)}

제품이 없을 때와 있을 때 다른 UI를 표시합니다.

리스트 렌더링

{products.map((product) => (
  
    {/* 제품 카드 */}
  
))}

map(): 배열의 각 항목을 컴포넌트로 변환
key={product.id}: React가 각 항목을 추적하기 위한 고유 키

가격 포맷팅

{`₩${Number(product.variants.edges[0].node.price).toLocaleString()}`}

Number(): 문자열을 숫자로 변환
toLocaleString(): 천 단위 구분 (100000 → 100,000)
결과: ₩100,000

5. 네비게이션 추가

마지막으로 앱 메뉴에 "제품 목록" 링크를 추가합니다.

`app/routes/app.tsx` 수정

export default function App() {
  const { apiKey } = useLoaderData();

  return (
    
      
        Home
        제품 목록  {/* ← 추가 */}
        Additional page
      
      
    
  );
}

이제 상단 네비게이션에 "제품 목록" 탭이 표시됩니다!

6. 완성 및 테스트

전체 파일

app/routes/app.products.tsx (전체):

import type { LoaderFunctionArgs } from "react-router";
import { useLoaderData } from "react-router";
import { authenticate } from "../shopify.server";

interface Product {
  id: string;
  title: string;
  status: string;
  totalInventory: number;
  featuredImage?: {
    url: string;
  };
  variants: {
    edges: Array<{
      node: {
        price: string;
      };
    }>;
  };
}

interface LoaderData {
  products: Product[];
}

export const loader = async ({ request }: LoaderFunctionArgs) => {
  const { admin } = await authenticate.admin(request);

  const response = await admin.graphql(
    `#graphql
      query getProducts {
        products(first: 50) {
          edges {
            node {
              id
              title
              status
              totalInventory
              featuredImage {
                url
              }
              variants(first: 1) {
                edges {
                  node {
                    price
                  }
                }
              }
            }
          }
        }
      }
    `
  );

  const responseJson = await response.json();
  const products = responseJson.data?.products?.edges.map((edge: any) => edge.node) || [];

  return { products };
};

export default function ProductsPage() {
  const { products } = useLoaderData();

  return (
    
      
        {products.length === 0 ? (
          
            제품이 없습니다. Shopify Admin에서 제품을 추가해보세요!
          
        ) : (
          
            
              총 {products.length}개의 제품
            
            
              {products.map((product) => (
                
                  
                    {product.featuredImage && (
                      
                    )}
                    
                      
                        {product.title}
                      
                      
                        
                          가격:{" "}
                          {product.variants.edges[0]?.node.price
                            ? `₩${Number(product.variants.edges[0].node.price).toLocaleString()}`
                            : "가격 없음"}
                        
                        
                          재고: {product.totalInventory}개
                        
                        
                          상태:{" "}
                          {product.status === "ACTIVE" ? "활성" : "비활성"}
                        
                      
                    
                  
                
              ))}
            
          
        )}
      

      
        
          이 페이지는 Shopify Admin GraphQL API를 사용하여 스토어의 제품 목록을 가져옵니다.
        
        
          제품을 추가하려면 Shopify Admin → 제품 메뉴에서 추가하세요.
        
      
    
  );
}

테스트

개발 서버 실행:
```
npm run dev
```

Shopify Admin에서 앱 열기:

https://your-store.myshopify.com/admin/apps/integrated-projection-app

"제품 목록" 탭 클릭
결과 확인:
- 스토어의 모든 제품이 목록으로 표시됨
- 각 제품의 이미지, 이름, 가격, 재고, 상태 확인

7. 확장 아이디어

이 기본 제품 목록 페이지를 다양하게 확장할 수 있습니다:

검색 기능

const [searchTerm, setSearchTerm] = useState("");
const filteredProducts = products.filter(p =>
  p.title.toLowerCase().includes(searchTerm.toLowerCase())
);

정렬 기능

const sortedProducts = [...products].sort((a, b) => {
  if (sortBy === "price") {
    return parseFloat(a.variants.edges[0]?.node.price || "0") -
           parseFloat(b.variants.edges[0]?.node.price || "0");
  }
  if (sortBy === "inventory") {
    return a.totalInventory - b.totalInventory;
  }
  return 0;
});

페이지네이션

// 다음 50개 제품 가져오기
const response = await admin.graphql(`
  query getProducts($cursor: String) {
    products(first: 50, after: $cursor) {
      edges {
        node { ... }
        cursor
      }
      pageInfo {
        hasNextPage
      }
    }
  }
`, { variables: { cursor: lastCursor } });

제품 상세 페이지

app/routes/app.products.$id.tsx

제품 ID를 동적 매개변수로 받아 상세 정보 표시

8. 배운 핵심 개념

React Router Loader

export const loader = async ({ request }) => {
  // 서버에서 데이터 가져오기
  const data = await fetchData();
  return { data };
};

export default function Component() {
  const { data } = useLoaderData();
  // 데이터 사용
}

장점:

페이지 로드 전에 데이터 준비
로딩 상태 자동 관리
SEO 친화적 (서버 사이드 렌더링)

GraphQL 쿼리 최적화

필요한 필드만 정확히 요청:

# ✅ 좋은 예: 필요한 것만
query {
  products(first: 50) {
    edges {
      node {
        id
        title
        totalInventory
      }
    }
  }
}

# ❌ 나쁜 예: 모든 필드
query {
  products(first: 50) {
    edges {
      node {
        # 수십 개 필드 모두 요청
      }
    }
  }
}

Polaris Web Components

Shopify 스타일 UI를 쉽게 구현:

      {/* 페이지 레이아웃 */}
   {/* 섹션 구분 */}
     {/* flexbox 레이아웃 */}
       {/* 카드 컨테이너 */}
      {/* 타이포그래피 */}

마치며

축하합니다! 첫 번째 실전 Shopify 앱 기능을 완성했습니다! 🎉

이 제품 목록 페이지를 만들면서:

✅ Shopify GraphQL API로 실제 데이터를 조회했습니다 ✅ React Router Loader로 서버 사이드 데이터 페칭을 구현했습니다 ✅ Polaris Web Components로 Shopify 스타일 UI를 만들었습니다 ✅ TypeScript로 타입 안전성을 확보했습니다

다음 단계로는:

제품 상세 페이지 만들기
제품 생성/수정 기능 추가
스토어 대시보드 구현
주문 관리 기능 개발

실제로 움직이는 앱을 만들면서 배우는 것이 가장 빠른 학습 방법입니다!

다음 글 예고: Shopify API로 스토어 대시보드 만들기

GitHub 저장소: [링크 추가 예정]

질문이나 피드백은 댓글로 남겨주세요! 💬

Shopify Admin API 완벽 가이드: GraphQL로 스토어 데이터 다루기

Mon, 08 Dec 2025 03:14:36 GMT

Shopify 커스텀 앱에서 API를 사용해 스토어 데이터를 조회하고 수정하는 방법을 상세히 알아봅니다.

들어가며

Shopify 커스텀 앱을 만들면서 가장 중요한 것은 Shopify Admin API를 이해하는 것입니다. API를 통해 제품, 주문, 고객 등 스토어의 모든 데이터에 접근할 수 있습니다.

이번 글에서는 Shopify Admin GraphQL API의 동작 원리부터 실제 사용법까지 모두 다루겠습니다.

1. Shopify Admin API란?

API의 역할

Shopify Admin API는 스토어의 데이터베이스에 접근할 수 있게 해주는 인터페이스입니다.

커스텀 앱 (React)
    ↓
API 요청 (GraphQL)
    ↓
Shopify 서버
    ↓
스토어 데이터베이스
    ↓
응답 (JSON)
    ↓
커스텀 앱에서 표시

GraphQL vs REST

Shopify는 두 가지 API를 제공하지만, GraphQL을 권장합니다:

특징	REST API	GraphQL API
요청 횟수	여러 번 필요	한 번으로 해결
데이터	전체 반환 (오버페칭)	필요한 것만 요청
타입 안정성	약함	강함
최신 기능	제한적	우선 지원

예시 비교:

// REST API - 3번 요청 필요
const product = await fetch('/admin/api/2025-01/products/123.json');
const images = await fetch('/admin/api/2025-01/products/123/images.json');
const variants = await fetch('/admin/api/2025-01/products/123/variants.json');

// GraphQL - 1번 요청으로 모두 가져오기
const data = await admin.graphql(`
  query {
    product(id: "gid://shopify/Product/123") {
      title
      images(first: 10) { edges { node { url } } }
      variants(first: 10) { edges { node { price } } }
    }
  }
`);

2. API 통신 방식 이해하기

기본 구조

커스텀 앱에서 Shopify API를 호출하는 전체 플로우:

// app/routes/app.products.tsx
export const loader = async ({ request }: LoaderFunctionArgs) => {
  // ① 인증된 admin 객체 가져오기
  const { admin } = await authenticate.admin(request);

  // ② GraphQL 쿼리 실행
  const response = await admin.graphql(`
    query getProducts {
      products(first: 50) {
        edges {
          node {
            id
            title
            totalInventory
          }
        }
      }
    }
  `);

  // ③ 응답 파싱
  const responseJson = await response.json();

  // ④ 데이터 추출 및 반환
  const products = responseJson.data?.products?.edges.map(e => e.node);
  return { products };
};

실제 HTTP 요청 내부

admin.graphql() 호출 시 내부적으로 일어나는 일:

1. HTTP POST 요청 전송
   ↓
   URL: https://your-store.myshopify.com/admin/api/2025-10/graphql.json

   Headers:
     - X-Shopify-Access-Token: [accessToken from DB]
     - Content-Type: application/json

   Body:
     {
       "query": "query getProducts { products(first: 50) { ... } }"
     }

2. Shopify 서버 처리
   ↓
   - 토큰 검증
   - 권한(scopes) 확인
   - 데이터베이스 쿼리 실행

3. JSON 응답 반환
   ↓
   {
     "data": {
       "products": {
         "edges": [
           {
             "node": {
               "id": "gid://shopify/Product/123",
               "title": "멋진 티셔츠",
               "totalInventory": 100
             }
           }
         ]
       }
     }
   }

3. GraphQL 쿼리 구조 파헤치기

기본 문법

query 쿼리이름 {           # 쿼리 이름 (선택사항)
  리소스(인자들) {         # products, orders 등
    필드1                 # id, title 등
    필드2
    관계필드 {            # 중첩된 데이터
      하위필드
    }
  }
}

실전 예제: 제품 조회

query getProducts {
  products(first: 50) {          # 제품 50개 가져와
    edges {                      # GraphQL 페이지네이션 구조
      node {                     # 실제 제품 데이터
        id                       # 제품 ID
        title                    # 제품명
        description              # 설명
        status                   # ACTIVE, DRAFT, ARCHIVED
        totalInventory           # 총 재고

        # 중첩: 이미지 정보
        images(first: 5) {
          edges {
            node {
              url
              altText
            }
          }
        }

        # 중첩: 변형 정보 (사이즈, 색상 등)
        variants(first: 10) {
          edges {
            node {
              id
              title
              price
              sku
              inventoryQuantity
            }
          }
        }
      }
    }
  }
}

응답 구조

{
  "data": {
    "products": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/Product/8453618196773",
            "title": "Red Snowboard",
            "description": "A cool red snowboard",
            "status": "ACTIVE",
            "totalInventory": 100,
            "images": {
              "edges": [
                {
                  "node": {
                    "url": "https://cdn.shopify.com/...",
                    "altText": "Red snowboard front view"
                  }
                }
              ]
            },
            "variants": {
              "edges": [
                {
                  "node": {
                    "id": "gid://shopify/ProductVariant/123",
                    "title": "Medium",
                    "price": "299.99",
                    "sku": "RED-SNO-M",
                    "inventoryQuantity": 50
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

왜 `edges`와 `node`를 사용하나?

GraphQL Relay 스타일 페이지네이션 때문입니다:

products {
  edges {           # 배열: 각 항목을 감싸는 래퍼
    node {          # 실제 데이터
      id
      title
    }
    cursor         # 페이지네이션용 커서
  }
  pageInfo {       # 페이지 정보
    hasNextPage
    hasPreviousPage
  }
}

이 구조 덕분에 "다음 50개" 가져오기가 쉽습니다:

query {
  products(first: 50, after: "커서값") {
    edges {
      node { ... }
      cursor
    }
  }
}

4. 조회 가능한 주요 데이터

Products (제품)

query {
  products(first: 100) {
    edges {
      node {
        id
        title
        description
        descriptionHtml
        handle                # URL 슬러그
        status               # ACTIVE, DRAFT, ARCHIVED
        vendor               # 공급업체
        productType          # 제품 타입
        tags                 # 태그 배열
        createdAt
        updatedAt
        totalInventory       # 총 재고

        priceRangeV2 {       # 가격 범위
          minVariantPrice {
            amount
            currencyCode
          }
          maxVariantPrice {
            amount
            currencyCode
          }
        }

        seo {                # SEO 정보
          title
          description
        }
      }
    }
  }
}

Orders (주문)

query {
  orders(first: 100) {
    edges {
      node {
        id
        name                         # 주문 번호 (#1001)
        email
        phone
        createdAt

        # 상태
        displayFulfillmentStatus     # FULFILLED, UNFULFILLED
        displayFinancialStatus       # PAID, PENDING, REFUNDED

        # 금액
        currentTotalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        currentSubtotalPriceSet {
          shopMoney { amount }
        }
        totalShippingPriceSet {
          shopMoney { amount }
        }

        # 주문 아이템
        lineItems(first: 100) {
          edges {
            node {
              title
              quantity
              variant {
                id
                title
                price
                sku
              }
              originalUnitPriceSet {
                shopMoney { amount }
              }
            }
          }
        }

        # 배송지
        shippingAddress {
          firstName
          lastName
          address1
          address2
          city
          province
          country
          zip
        }

        # 배송 추적
        fulfillments {
          id
          status
          trackingNumber
          trackingUrl
        }
      }
    }
  }
}

Shop (스토어 정보)

query {
  shop {
    id
    name                    # 스토어명
    email
    myshopifyDomain        # your-store.myshopify.com
    primaryDomain {
      url                  # 커스텀 도메인
      host
    }
    currencyCode           # KRW, USD 등
    timezoneAbbreviation   # KST

    billingAddress {
      address1
      city
      country
      zip
    }

    plan {
      displayName          # Basic, Shopify, Advanced
    }
  }
}

Inventory (재고)

query {
  inventoryItems(first: 50) {
    edges {
      node {
        id
        sku
        tracked              # 재고 추적 여부

        inventoryLevels(first: 10) {
          edges {
            node {
              available        # 사용 가능 재고
              incoming         # 입고 예정
              location {
                id
                name           # 창고명
                address {
                  city
                  country
                }
              }
            }
          }
        }
      }
    }
  }
}

Collections (컬렉션)

query {
  collections(first: 50) {
    edges {
      node {
        id
        title
        description
        handle
        productsCount

        products(first: 100) {
          edges {
            node {
              id
              title
            }
          }
        }

        image {
          url
        }
      }
    }
  }
}

Discounts (할인)

query {
  discountNodes(first: 50) {
    edges {
      node {
        id
        discount {
          ... on DiscountCodeBasic {
            title
            codes(first: 10) {
              edges {
                node {
                  code           # 할인 코드
                }
              }
            }

            customerGets {
              value {
                ... on DiscountPercentage {
                  percentage
                }
                ... on DiscountAmount {
                  amount { amount }
                }
              }
            }

            startsAt
            endsAt
            usageLimit
          }
        }
      }
    }
  }
}

5. Mutation: 데이터 생성 및 수정

조회만 하는 게 아니라 생성, 수정, 삭제도 가능합니다!

제품 생성

const response = await admin.graphql(`
  mutation createProduct($input: ProductCreateInput!) {
    productCreate(input: $input) {
      product {
        id
        title
        status
      }
      userErrors {
        field
        message
      }
    }
  }
`, {
  variables: {
    input: {
      title: "새로운 티셔츠",
      descriptionHtml: "멋진 티셔츠입니다",
      vendor: "내 브랜드",
      productType: "의류",
      tags: ["신상", "베스트"],
      status: "ACTIVE"
    }
  }
});

제품 수정

const response = await admin.graphql(`
  mutation updateProduct($input: ProductInput!) {
    productUpdate(input: $input) {
      product {
        id
        title
      }
      userErrors {
        field
        message
      }
    }
  }
`, {
  variables: {
    input: {
      id: "gid://shopify/Product/123",
      title: "수정된 제품명",
      tags: ["할인중"]
    }
  }
});

제품 삭제

const response = await admin.graphql(`
  mutation deleteProduct($input: ProductDeleteInput!) {
    productDelete(input: $input) {
      deletedProductId
      userErrors {
        field
        message
      }
    }
  }
`, {
  variables: {
    input: {
      id: "gid://shopify/Product/123"
    }
  }
});

가격 일괄 변경

const response = await admin.graphql(`
  mutation bulkUpdateVariants($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
    productVariantsBulkUpdate(productId: $productId, variants: $variants) {
      productVariants {
        id
        price
      }
      userErrors {
        field
        message
      }
    }
  }
`, {
  variables: {
    productId: "gid://shopify/Product/123",
    variants: [
      { id: "gid://shopify/ProductVariant/456", price: "29.99" },
      { id: "gid://shopify/ProductVariant/789", price: "39.99" }
    ]
  }
});

주문 상태 업데이트

const response = await admin.graphql(`
  mutation fulfillOrder($input: FulfillmentCreateV2Input!) {
    fulfillmentCreateV2(fulfillment: $input) {
      fulfillment {
        id
        status
        trackingInfo {
          number
          url
        }
      }
      userErrors {
        field
        message
      }
    }
  }
`, {
  variables: {
    input: {
      lineItemsByFulfillmentOrder: [{
        fulfillmentOrderId: "gid://shopify/FulfillmentOrder/123"
      }],
      trackingInfo: {
        number: "1234567890",
        url: "https://tracking.example.com/1234567890"
      }
    }
  }
});

6. 권한(Scopes) 관리

권한 설정

API를 사용하려면 적절한 권한이 필요합니다.

shopify.app.toml:

[access_scopes]
scopes = "write_products,read_orders,read_customers"

주요 권한 종류

권한	설명	용도
`read_products`	제품 조회	제품 목록 표시
`write_products`	제품 생성/수정/삭제	제품 관리
`read_orders`	주문 조회	주문 내역 보기
`write_orders`	주문 수정	주문 상태 변경
`read_customers`	고객 조회	고객 목록 (승인 필요)
`write_customers`	고객 생성/수정	고객 정보 관리 (승인 필요)
`read_inventory`	재고 조회	재고 현황
`write_inventory`	재고 수정	재고 조정
`read_discounts`	할인 조회	할인 코드 보기
`write_discounts`	할인 생성/수정	프로모션 관리

권한 변경 시 주의사항

// 1. shopify.app.toml에서 권한 추가
scopes = "write_products,read_orders"  // 기존
        ↓
scopes = "write_products,read_orders,read_inventory"  // 추가

// 2. 개발 서버 재시작
npm run dev

// 3. 개발 모드: 자동 승인
// 4. 프로덕션: 사용자가 재승인 필요!

7. Protected Customer Data (보호된 고객 데이터)

왜 고객 데이터는 특별한가?

Shopify는 고객 개인정보 보호를 위해 고객 데이터 접근을 제한합니다.

// ❌ 개발 중에는 에러 발생
const response = await admin.graphql(`
  query {
    customers(first: 10) {
      edges {
        node {
          id
          email
          firstName
        }
      }
    }
  }
`);

// Error: This app is not approved to access the Customer object.

고객 데이터 접근하려면?

개인정보 보호 정책 작성 및 제출
앱 심사 신청
Shopify의 승인 대기
승인 후 사용 가능

자세한 내용: https://shopify.dev/docs/apps/launch/protected-customer-data

대안: 주문의 고객 정보

주문 데이터에는 일부 고객 정보가 포함되어 있습니다 (제한적):

query {
  orders(first: 10) {
    edges {
      node {
        email              # 주문 이메일 (허용)
        shippingAddress {  # 배송지 (허용)
          firstName
          lastName
          address1
        }
        # ✅ customer 객체는 접근 불가
      }
    }
  }
}

8. 실전 팁

1. GraphiQL로 쿼리 테스트

개발 서버 실행 중 http://localhost:3457 접속:

npm run dev
# → GraphiQL server started on port 3457

브라우저에서 직접 쿼리를 작성하고 테스트할 수 있습니다!

2. 에러 처리

const response = await admin.graphql(`
  mutation createProduct($input: ProductInput!) {
    productCreate(input: $input) {
      product { id }
      userErrors {        // ✅ 항상 userErrors 체크!
        field
        message
      }
    }
  }
`, { variables: { input: {...} } });

const data = await response.json();

if (data.data?.productCreate?.userErrors?.length > 0) {
  console.error("에러:", data.data.productCreate.userErrors);
  // 사용자에게 에러 표시
}

3. 페이지네이션

대량의 데이터는 페이지네이션으로:

let cursor = null;
let allProducts = [];

while (true) {
  const response = await admin.graphql(`
    query getProducts($cursor: String) {
      products(first: 250, after: $cursor) {
        edges {
          node { id title }
          cursor
        }
        pageInfo {
          hasNextPage
        }
      }
    }
  `, { variables: { cursor } });

  const data = await response.json();
  const edges = data.data.products.edges;

  allProducts.push(...edges.map(e => e.node));

  if (!data.data.products.pageInfo.hasNextPage) break;
  cursor = edges[edges.length - 1].cursor;
}

console.log(`총 ${allProducts.length}개 제품`);

4. 성능 최적화

여러 데이터를 한 번에:

// ❌ 나쁜 예: 3번 요청
const products = await admin.graphql(`query { products {...} }`);
const orders = await admin.graphql(`query { orders {...} }`);
const shop = await admin.graphql(`query { shop {...} }`);

// ✅ 좋은 예: 1번 요청
const response = await admin.graphql(`
  query getDashboardData {
    products(first: 50) { ... }
    orders(first: 50) { ... }
    shop { ... }
  }
`);

9. 주요 리소스

공식 문서

개발 도구

GraphiQL: 브라우저에서 쿼리 테스트
Shopify CLI: 앱 개발 및 배포
GraphQL Codegen: TypeScript 타입 자동 생성

마치며

Shopify Admin API는 매우 강력합니다. GraphQL 덕분에:

✅ 필요한 데이터만 정확히 가져올 수 있습니다 ✅ 한 번의 요청으로 복잡한 데이터 조회 가능 ✅ 타입 안정성으로 버그 감소 ✅ 실시간으로 스토어 데이터 관리

이제 API의 동작 원리를 이해했으니, 다음 단계는 실제로 유용한 기능을 만드는 것입니다!

다음 포스트에서는 이 API를 활용해 실전 기능(대시보드, 제품 관리 등)을 구현하는 방법을 다루겠습니다.

질문이나 피드백은 댓글로 남겨주세요! 💬

다음 글 예고: Shopify API로 실전 대시보드 만들기

Shopify 커스텀 앱 개발 입문: 아키텍처부터 세계시계 앱 만들기까지

Mon, 08 Dec 2025 02:25:15 GMT

Shopify 커스텀 앱의 구조를 이해하고, React Router 기반으로 세계시계 앱을 개발한 과정을 정리합니다.

들어가며

Shopify 스토어에 필요한 기능을 직접 만들어 추가할 수 있는 커스텀 앱 개발에 도전했습니다. 처음에는 앱이 어떻게 동작하는지 전혀 몰랐지만, 하나씩 파헤치며 배운 내용을 공유합니다.

1. Shopify 커스텀 앱이란?

Shopify 커스텀 앱은 Shopify Admin 내부에 임베디드되어 실행되는 웹 애플리케이션입니다. 상점 관리자가 Shopify Admin에서 앱을 클릭하면, iframe 안에 우리가 만든 앱이 표시됩니다.

전체 아키텍처

┌─────────────────────────────────────────────────────────────┐
│              Shopify Admin (브라우저)                         │
│          https://your-store.myshopify.com/admin             │
└────────────────────┬────────────────────────────────────────┘
                     │
                     │ (iframe으로 embedded)
                     ▼
┌─────────────────────────────────────────────────────────────┐
│               Your Custom App (React Router)                │
│                                                             │
│  ┌──────────────┐      ┌──────────────┐                     │
│  │ React 컴포넌트 │ ◄──► │ Shopify API  │                     │
│  └──────────────┘      └──────────────┘                     │
│         │                     │                             │
│         ▼                     ▼                             │
│  ┌──────────────────────────────────┐                       │
│  │    Prisma (Session Storage)      │                       │
│  │         SQLite Database           │                      │
│  └──────────────────────────────────┘                       │
└─────────────────────────────────────────────────────────────┘

2. 프로젝트 구조 이해하기

디렉토리 구조

integrated-projection-app/
├── app/
│   ├── routes/              # 페이지들 (라우팅)
│   │   ├── app.tsx          # 앱 레이아웃 (네비게이션 포함)
│   │   ├── app._index.tsx   # 메인 페이지 (Home)
│   │   ├── app.clock.tsx    # 시계 페이지 (우리가 만들 것!)
│   │   ├── auth.$.tsx       # OAuth 콜백
│   │   └── webhooks.*.tsx   # 웹훅 핸들러
│   ├── shopify.server.ts    # Shopify 설정 (핵심!)
│   ├── db.server.ts         # 데이터베이스 연결
│   └── root.tsx             # HTML 루트
├── prisma/
│   └── schema.prisma        # 데이터베이스 스키마
├── shopify.app.toml         # Shopify 앱 설정
└── package.json

핵심 파일 역할

`shopify.server.ts` - 앱의 심장

const shopify = shopifyApp({
  apiKey: process.env.SHOPIFY_API_KEY,        // 앱 식별자
  apiSecretKey: process.env.SHOPIFY_API_SECRET, // 비밀키
  apiVersion: ApiVersion.October25,            // API 버전
  scopes: process.env.SCOPES?.split(","),      // 권한
  sessionStorage: new PrismaSessionStorage(prisma), // 세션 저장
});

이 파일이 하는 일:

OAuth 인증 처리
Session 관리
Shopify Admin API 클라이언트 제공
웹훅 등록

`prisma/schema.prisma` - 세션 저장소

model Session {
  id          String    @id
  shop        String      # tony-test-store-989.myshopify.com
  accessToken String      # API 호출용 토큰
  scope       String?     # write_products
  expires     DateTime?
  userId      BigInt?
  // ...
}

각 상점의 인증 정보를 저장합니다. 이 accessToken으로 Shopify API를 호출할 수 있습니다.

3. 앱 동작 원리 (플로우)

Step 1: 인증 (OAuth)

1. 사용자가 앱 클릭
   ↓
2. /auth/login → Shopify OAuth 페이지로 리다이렉트
   ↓
3. 사용자 권한 승인
   ↓
4. /auth/callback → 토큰 받아서 Prisma DB에 저장
   ↓
5. /app으로 리다이렉트 (앱 메인 페이지)

Step 2: 인증된 요청 처리

모든 /app/* 라우트는 자동으로 인증을 체크합니다:

// app/routes/app.tsx
export const loader = async ({ request }: LoaderFunctionArgs) => {
  await authenticate.admin(request);  // ← 인증 체크!
  return { apiKey: process.env.SHOPIFY_API_KEY || "" };
};

Step 3: Shopify API 호출

export const action = async ({ request }: ActionFunctionArgs) => {
  const { admin } = await authenticate.admin(request);

  // GraphQL로 Shopify API 호출
  const response = await admin.graphql(`
    mutation populateProduct($product: ProductCreateInput!) {
      productCreate(product: $product) {
        product { id title }
      }
    }`,
    { variables: { product: { title: "Red Snowboard" } } }
  );

  return await response.json();
};

데이터 흐름:

사용자 클릭 → React 컴포넌트 → Loader/Action 함수 →
Shopify API 호출 → 결과 반환 → UI 업데이트

4. 개발 환경 이해하기

개발 모드 vs 프로덕션

개발 모드 (현재)

npm run dev

로컬 컴퓨터에서 실행 (localhost:55064)
Cloudflare 터널로 임시 공개 URL 생성
Shopify가 터널을 통해 로컬 앱에 접속
무료, 빠른 테스트 가능

프로덕션 모드

npm run deploy

실제 서버에 배포 (Google Cloud Run, Fly.io 등)
고정 도메인 사용
Cloudflare와 무관, 안정적 운영

왜 Cloudflare 터널을 사용하나?

Shopify는 공개 URL이 필요합니다:

OAuth 콜백을 받아야 함
웹훅을 받아야 함
iframe에 앱을 표시해야 함

로컬 개발 중에는 localhost가 외부에서 접근 불가하므로, Cloudflare 터널이 localhost를 인터넷에 노출시켜줍니다.

5. 실습: 세계시계 앱 만들기

이제 배운 내용을 바탕으로 실제 기능을 만들어봅시다!

5-1. 새 페이지 생성하기

파일 생성 규칙

React Router는 파일명 = URL 구조 방식입니다:

app/routes/
├── app.tsx              → /app (레이아웃)
├── app._index.tsx       → /app (메인)
├── app.clock.tsx        → /app/clock ✅ 우리가 만들 파일!

`app/routes/app.clock.tsx` 생성

import { useEffect, useState } from "react";

interface City {
  name: string;
  timezone: string;
  flag: string;
}

const cities: City[] = [
  { name: "서울", timezone: "Asia/Seoul", flag: "🇰🇷" },
  { name: "런던", timezone: "Europe/London", flag: "🇬🇧" },
  { name: "상하이", timezone: "Asia/Shanghai", flag: "🇨🇳" },
  { name: "뉴욕", timezone: "America/New_York", flag: "🇺🇸" },
  { name: "파리", timezone: "Europe/Paris", flag: "🇫🇷" },
  { name: "남아공", timezone: "Africa/Johannesburg", flag: "🇿🇦" },
];

export default function ClockPage() {
  const [currentTime, setCurrentTime] = useState(new Date());

  // 1초마다 시간 업데이트
  useEffect(() => {
    const timer = setInterval(() => {
      setCurrentTime(new Date());
    }, 1000);

    return () => clearInterval(timer);
  }, []);

  // 특정 타임존의 시간 포맷팅
  const getTimeForTimezone = (timezone: string) => {
    return new Intl.DateTimeFormat("ko-KR", {
      timeZone: timezone,
      hour: "2-digit",
      minute: "2-digit",
      second: "2-digit",
      hour12: false,
    }).format(currentTime);
  };

  // 특정 타임존의 날짜 포맷팅
  const getDateForTimezone = (timezone: string) => {
    return new Intl.DateTimeFormat("ko-KR", {
      timeZone: timezone,
      year: "numeric",
      month: "long",
      day: "numeric",
      weekday: "long",
    }).format(currentTime);
  };

  return (
    
      
        
          {cities.map((city) => (
            
              
                
                  {city.flag} {city.name}
                
                
                  {getTimeForTimezone(city.timezone)}
                
                
                  {getDateForTimezone(city.timezone)}
                
              
            
          ))}
        
      
    
  );
}

5-2. 네비게이션에 링크 추가

`app/routes/app.tsx` 수정

export default function App() {
  const { apiKey } = useLoaderData();

  return (
    
      
        Home
        Additional page
        시계 {/* ✅ 추가! */}
      
      
    
  );
}

5-3. 결과 확인

브라우저에서 Shopify Admin → 앱 → 시계 탭 클릭!

상단 네비게이션:

Home | Additional page | 시계

각 도시의 시간이 실시간으로 똑딱똑딱! ⏰

6. 핵심 개념 정리

Polaris Web Components

Shopify에서 제공하는 UI 라이브러리입니다. 태그로 사용:


  
    버튼
    텍스트

React Router의 Loader와 Action

Loader: 페이지 로드 시 데이터 가져오기 (GET)
Action: 폼 제출 시 데이터 처리 (POST)

// 데이터 가져오기
export const loader = async ({ request }) => {
  const { admin } = await authenticate.admin(request);
  const data = await admin.graphql(`query { ... }`);
  return data;
};

// 데이터 처리
export const action = async ({ request }) => {
  const { admin } = await authenticate.admin(request);
  const result = await admin.graphql(`mutation { ... }`);
  return result;
};

타임존 처리

JavaScript의 Intl.DateTimeFormat API를 사용하면 타임존 변환이 간단합니다:

new Intl.DateTimeFormat("ko-KR", {
  timeZone: "America/New_York",
  hour: "2-digit",
  minute: "2-digit",
}).format(new Date());
// → "03:45"

7. 배운 점과 느낀 점

이해한 것들

✅ Shopify 커스텀 앱은 iframe 안에서 실행되는 웹앱이다 ✅ OAuth로 상점과 안전하게 연결하고, Session을 DB에 저장한다 ✅ React Router의 파일명이 곧 URL 구조다 ✅ Polaris Web Components로 Shopify 스타일 UI를 쉽게 만들 수 있다 ✅ 개발 모드는 Cloudflare 터널 사용, 프로덕션은 실제 서버 배포

새로운 페이지 만들기 패턴

app/routes/app.페이지명.tsx 파일 생성
app/routes/app.tsx에 네비게이션 링크 추가
끝!

다음 단계

데이터베이스에 사용자 데이터 저장하기
Shopify Admin API로 제품/주문 관리하기
웹훅으로 실시간 이벤트 처리하기
프로덕션 배포하기

마치며

처음에는 막연했던 Shopify 커스텀 앱 개발이, 하나씩 뜯어보니 결국은 React 웹앱 + OAuth + API 호출의 조합이었습니다.

세계시계라는 간단한 기능이지만, 페이지 생성부터 라우팅, 실시간 업데이트까지 구현하며 Shopify 앱 개발의 전체 흐름을 익힐 수 있었습니다.

다음 포스트에서는 실제 Shopify 데이터(제품, 주문 등)를 다루는 앱을 만들어보겠습니다!

참고 자료

GitHub 저장소: [링크 추가 예정] 질문이나 피드백은 댓글로 남겨주세요! 💬

Shopify 독립 출판 서점 테마 제작기: The Moved Mover

Fri, 05 Dec 2025 02:20:01 GMT

프로젝트 개요

"The Moved Mover"는 독립 출판물, 아티스트북, 그리고 창작자들의 목소리를 담은 책들을 판매하는 온라인 서점을 위한 Shopify 테마입니다.

"우리는 매 순간 흔들리고, 움직이며, 변합니다. 그리고 그 흔들림은 다시 누군가를 움직입니다. The Moved Mover는 그 파동을 기록으로 남깁니다."

프로젝트 저장소: learn-shopify-theme 작업 기간: 2025년 11월 ~ 12월 개발 환경: Shopify Liquid, HTML/CSS

프로젝트 동기

독립 출판의 가치를 전달하고, 창작자들의 목소리를 효과적으로 전달할 수 있는 온라인 플랫폼이 필요했습니다. 기존의 범용 커머스 테마들은 독립 출판의 철학과 브랜드 아이덴티티를 표현하기에 한계가 있었고, 이에 맞춤형 Shopify 테마를 직접 제작하게 되었습니다.

기술 스택

핵심 기술

Shopify Liquid: Shopify의 템플릿 언어
HTML5 / CSS3: 시맨틱 마크업 및 스타일링
JavaScript: 인터랙션 및 동적 기능 구현
Shopify CLI: 테마 개발 및 배포 도구

개발 도구

VS Code: Shopify Liquid Extension 활용
Git: 버전 관리
Shopify Theme Dev: 로컬 개발 환경

프로젝트 구조

learn-shopify-theme/
├── assets/              # 정적 자산 (CSS, JS, 이미지, 비디오)
│   ├── critical.css     # 필수 CSS
│   └── video.mp4        # 히어로 배경 비디오
├── blocks/              # 재사용 가능한 UI 컴포넌트
├── config/              # 테마 전역 설정
├── layout/              # 페이지 최상위 래퍼
│   └── theme.liquid
├── locales/             # 다국어 번역 파일
├── sections/            # 페이지 섹션 컴포넌트
│   ├── home-hero.liquid
│   ├── featured-books.liquid
│   ├── books-catalog.liquid
│   ├── header.liquid
│   ├── about-hero.liquid
│   ├── submission-form.liquid
│   └── ...
├── snippets/            # 재사용 가능한 코드 조각
└── templates/           # 페이지 템플릿
    ├── index.json       # 홈페이지
    ├── collection.json  # 컬렉션 페이지
    └── ...

주요 기능 구현

1. 홈 히어로 섹션 (home-hero.liquid)

홈페이지의 첫인상을 결정하는 풀스크린 히어로 배너를 구현했습니다.

주요 특징

비디오 배경 지원: Shopify CDN에서 호스팅되는 배경 비디오
이미지 폴백: 비디오 미지원 시 이미지로 대체
Overlay 투명도 조절: 30% 투명도로 비디오 가시성 향상
100vh 풀스크린: 모든 디바이스에서 전체 화면 표시
애니메이션: Fade-in 애니메이션으로 부드러운 등장 효과
스크롤 인디케이터: 바운스 애니메이션으로 사용자 유도

기술적 구현

{% if section.settings.hero_video_url != blank %}
  
    
  
{% elsif section.settings.hero_video_asset != blank %}
  
    
  
{% elsif section.settings.hero_image %}
  
{% endif %}

반응형 디자인

모바일에서 스크롤 인디케이터 숨김
버튼을 세로 방향으로 재배치
Clamp()를 활용한 유연한 폰트 사이즈

font-size: clamp(1.75rem, 5vw, 2.8rem);

2. 도서 카탈로그 (books-catalog.liquid)

독립 출판물을 카테고리별로 탐색할 수 있는 카탈로그 섹션입니다.

주요 특징

카테고리 필터링: 에세이, 소설, 시, 예술, 철학 등
검색 기능: 실시간 도서 검색
그리드 레이아웃: 반응형 그리드 시스템
호버 효과: 책 카드에 Overlay 및 CTA 버튼 표시
별점 시스템: 사용자 리뷰 표시

CSS Grid 구현

.books-catalog__grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
  gap: 2rem;
}

인터랙티브 필터 버튼

.books-catalog__filter-btn--active {
  background-color: currentColor;
  color: #ffffff !important;
  box-shadow: 0 4px 12px rgba(196, 163, 106, 0.3);
  transform: translateY(-2px);
}

3. 헤더 네비게이션 (header.liquid)

모든 페이지에서 일관된 네비게이션을 제공하는 고정 헤더입니다.

주요 특징

Sticky Header: 스크롤 시에도 상단 고정
드롭다운 메뉴: 도서 카테고리 하위 메뉴
장바구니 아이콘: 아이템 수 배지 표시
로고와 메뉴: 중앙 정렬 레이아웃
반응형: 모바일에서는 햄버거 메뉴로 전환 (향후 구현)

.header {
  position: sticky;
  top: 0;
  z-index: 100;
}

드롭다운 메뉴

.header__dropdown {
  position: absolute;
  opacity: 0;
  visibility: hidden;
  transform: translateY(-10px);
  transition: all 0.2s;
}

.header__menu-item--has-dropdown:hover .header__dropdown {
  opacity: 1;
  visibility: visible;
  transform: translateY(0);
}

4. About 페이지 히어로 (about-hero.liquid)

출판사의 철학과 스토리를 전달하는 About 페이지 히어로 섹션입니다.

주요 특징

조건부 배경 이미지: 이미지 설정 시에만 표시
CSS 변수 활용: 색상 관리의 일관성
Rich Text 지원: 부제목에 서식 있는 텍스트 적용
블랙/화이트 모드: 검은 배경에 흰색 텍스트 기본값

Rich Text 서브타이틀 처리


  {{ section.settings.subtitle }}

기술적 도전과 해결

1. 비디오 배경 최적화

문제

로컬 assets 폴더의 비디오 파일이 제대로 로드되지 않음
3MB 비디오 파일의 로딩 속도 이슈

해결

Shopify CDN에 비디오를 업로드하여 URL로 참조
hero_video_url 설정을 통해 CDN URL 직접 사용
autoplay muted loop playsinline 속성으로 자동 재생 최적화

2. 색상 일관성 관리

문제

여러 섹션에서 일관된 색상 사용 필요
Rich Text 내부의 중첩된
태그에서 색상 상속 이슈

해결

CSS 변수를 활용한 색상 관리
color: inherit로 중첩 요소에 색상 전달

.home-hero__subtitle {
  color: {{ section.settings.subtitle_color }};
}

.home-hero__subtitle p {
  margin: 0;
  color: inherit;
}

3. 반응형 레이아웃

문제

다양한 화면 크기에서 일관된 경험 제공
모바일에서 히어로 섹션의 가독성 저하

해결

CSS clamp() 함수로 유연한 폰트 사이즈
미디어 쿼리로 모바일 전용 스타일 적용
Flexbox와 Grid의 조합으로 반응형 레이아웃 구현

.home-hero__title {
  font-size: clamp(1.75rem, 5vw, 2.8rem);
}

@media (max-width: 768px) {
  .home-hero__buttons {
    flex-direction: column;
    width: 100%;
  }
}

4. Books Catalog 필터 UX

문제

초기에는 "All" 필터 버튼이 있었으나 UX 관점에서 불필요
필터링 상태를 명확히 표시할 필요

해결

"All" 버튼 제거 (커밋: 821ffe2)
--active 클래스로 활성 필터 시각화
Hover 효과로 인터랙션 강화

.books-catalog__filter-btn--active {
  background-color: currentColor;
  color: #ffffff !important;
  transform: translateY(-2px);
}

페이지 구성

홈페이지 (index.json)

Hero: 풀스크린 비디오 배너
Featured Books: 추천 도서 섹션
Publishers Spotlight: 협력 출판사 소개
Latest News: 최신 뉴스 및 이벤트
Newsletter: 뉴스레터 구독
Footer: 푸터 정보

정적 페이지

About (page.about.json): 소개, 가치, 팀
Authors (page.authors.json): 소속 작가 소개
Submission (page.submission.json): 원고 투고 안내
Contact (page.contact.json): 문의 폼
FAQ (page.faq.json): 자주 묻는 질문

컬렉션 페이지 (collection.json)

Books Catalog 섹션 포함
카테고리별 필터링 기능

디자인 시스템

색상 팔레트

Primary (Accent): #c4a36a - 골드 브라운
Background: #ffffff / #f9fafb / #2d2d2d
Text: #2d2d2d / #666666 / #999999
Border: #e0e0e0

타이포그래피

Heading: 700 weight, clamp로 반응형 사이즈
Body: 400-500 weight, 1.6-1.7 line-height
Letter Spacing: Heading에 -0.3px 적용

간격 시스템

Section Padding: 100px - 180px (상하)
Component Gap: 1rem - 2rem
Grid Gap: 2rem

성능 최적화

1. 이미지 최적화

Shopify의 image_url 필터로 크기 지정
Lazy loading 기본 지원

2. CSS 분리

critical.css: 모든 페이지에 필요한 필수 CSS
Section별 {% stylesheet %} 태그: 해당 섹션에만 필요한 CSS

3. 비디오 최적화

Shopify CDN 활용
autoplay muted loop playsinline 속성으로 자동 재생
Overlay로 콘텐츠 가독성 확보

Git 커밋 히스토리 하이라이트

비디오 히어로 구현 (12월 4일)

560b716 - Use Shopify CDN URL for hero video
fe81ed8 - Fix video hero banner display issue
4200bb4 - Add full-screen video hero banner with video.mp4

Books Catalog 개선 (12월 4일)

821ffe2 - Remove active filter button from Books Catalog section
5ccb811 - Enhance Books Catalog section design

About 섹션 리팩토링 (12월 4일)

dae7003 - Refactor About Hero section subtitle handling
1e43286 - Refactor About Hero section for conditional background image

README 업데이트 (12월 4일)

d92ce88 - Update README.md to reflect new theme name and features

배운 점

1. Shopify Liquid 템플릿 시스템

Liquid 문법과 Shopify 객체 구조 이해
Section Schema를 통한 커스터마이징 옵션 제공
{% stylesheet %}, {% javascript %} 태그의 중복 방지 기능

2. 컴포넌트 기반 설계

Sections와 Blocks를 활용한 모듈화
재사용 가능한 Snippets 작성
JSON 템플릿으로 페이지 구성 관리

3. CSS 설계 패턴

BEM 명명 규칙 적용
CSS 변수를 통한 일관된 디자인 시스템
clamp(), min(), max() 함수로 반응형 구현

4. 성능 최적화

Critical CSS 분리
Shopify CDN 활용
이미지 크기 최적화

5. 사용자 경험 (UX)

불필요한 UI 요소 제거 ("All" 필터 버튼)
명확한 인터랙션 피드백 (Hover, Active 상태)
접근성을 고려한 시맨틱 마크업

개선 사항 및 향후 계획

단기 개선 사항

모바일 햄버거 메뉴 구현
실제 상품 데이터와 연동
검색 기능 JavaScript 구현
카테고리 필터링 JavaScript 구현
장바구니 기능 고도화

중기 개선 사항

다국어 지원 (영문, 한글)
블로그 섹션 스타일링
상품 상세 페이지 커스터마이징
Wishlist 기능 추가
빠른 보기 (Quick View) 모달

장기 개선 사항

작가 인터뷰 시리즈 페이지
커뮤니티 기능 (독자 리뷰, Q&A)
추천 시스템 (개인화)
독립 출판 가이드 콘텐츠 허브
이벤트 및 북토크 일정 관리

프로젝트 회고

잘한 점

브랜드 아이덴티티 구현: "The Moved Mover"의 철학을 디자인으로 효과적으로 전달
모듈화된 구조: Sections과 Blocks로 재사용 가능하고 확장 가능한 구조 구축
성능 최적화: CDN 활용 및 CSS 분리로 로딩 속도 개선
상세한 문서화: README에 프로젝트 구조와 사용법을 명확히 기록

아쉬운 점

JavaScript 부재: 필터링과 검색 기능이 아직 정적 상태
테스트 부족: 다양한 브라우저와 디바이스에서의 테스트 필요
접근성: ARIA 라벨 및 키보드 네비게이션 개선 필요

다음 프로젝트에서 시도할 것

Alpine.js 또는 Vue.js: Liquid와 함께 사용할 경량 프레임워크
Storybook: 컴포넌트 문서화 및 테스트
E2E 테스트: Playwright 또는 Cypress로 테스트 자동화
성능 모니터링: Lighthouse CI 통합

참고 자료

마무리

"The Moved Mover" 테마 제작을 통해 Shopify의 강력한 커스터마이징 기능과 Liquid 템플릿 시스템을 깊이 있게 이해할 수 있었습니다. 독립 출판이라는 특수한 도메인에 맞춤화된 온라인 서점을 구축하면서, 단순히 기술적인 구현을 넘어 브랜드의 철학과 가치를 디지털 경험으로 전환하는 과정을 경험했습니다.

앞으로 이 테마를 기반으로 실제 독립 출판사들이 자신들의 이야기를 효과적으로 전달하고, 독자들과 의미 있는 연결을 만들어갈 수 있기를 기대합니다.

"우리는 움직일 때 아름답다" - The Moved Mover

프로젝트: The Moved Mover - Shopify Theme 작성일: 2025년 12월 5일 작성자: Eunjae Tony Lee

[React] 기능 개발 3단계

Mon, 27 Feb 2023 06:49:40 GMT

state 정의하기
event listener 만들기
동작할 코드 작성

a. HTML CSS 먼저 디자인 하기

b. 동작할 컴포넌트의 상태를 state로 선언하기

c. 컴포넌트의 기능 코딩하기

[React] WARNING 메시지 제거하기

Mon, 27 Feb 2023 06:02:47 GMT

/* eslint-disable */

React 코드를 실행하면 터미널에 이상한 경고 메시지가 떠요!

no-unused-vars 같은 경고 메시지가 출력됩니다. 경고 메시지가 출력되어도 앱을 실행하는 데에는 아무런 문제가 없지만 눈에 자꾸만 거슬리고 신경이 쓰이게 되지요. 경고 메시지가 출력되는 원인과 없앨 수 있는 방법을 알아보겠습니다.

0. ESLint란?

ESLint 때문입니다. ESLint는 자바스크립트 프로그램의 코드에 문법적인 오류가 있거나 표준에 맞지 않고 비효율적인 부분이 있을 때 이를 발견해 수정할 수 있도록 알려주는 역할을 하는 도구입니다.

React를 사용하면 별도로 ESLint를 설치하지 않아도 자동으로 적용되는 것이 기본이며 코드를 실행할 때 검출된 오류와 경고 메시지를 터미널에 출력합니다.

1. ESLint 오류 출력을 없애는 방법

1.1 코드의 오류를 수정하기

당연한 이야기지만 ESLint의 권고를 받아들이고 효율적이고 읽기 편한 방향으로 자신의 코드를 수정하면 오류 메시지를 제거할 수 있습니다. 저도 그렇게 하시기를 추천합니다. 하지만 많은 경우에, ESLint가 지나치게 사소한 부분까지 경고한다고 느끼는 분들이 많으실 것 같습니다. 특히 배우는 과정에서는 작은 경고라도 신경이 쓰여서 빠르게 실습을 진행하지 못하게 되는 경우도 많습니다. 그럴 때에는 다음 방법을 참고해 보세요.

1.2 ESLint의 작동을 해제하기

사소한 오류 메시지가 출력되는 것이 싫으면 ESLint의 작동을 중지시키는 방법도 있습니다.

코드의 맨 윗부분에 다음과 같은 부분을 주석으로 추가해주세요.

/* eslint-disable */

이렇게만 해도 ESLint의 자동 적용을 피할 수 있습니다. 만약 여러 개의 JS 파일이 import 되어 작동한다면 시스템 동작에 필요한 모든 JS 파일에 해당 코드를 추가해주어야 합니다!

[React] onClick() 함수 사용하기

Mon, 27 Feb 2023 05:35:47 GMT

1분 요약

{실행할 코드}}>


or

> ```javascript

[React] State를 사용하는 방법

Mon, 27 Feb 2023 05:28:12 GMT

import {useState} from 'react';
let [myState, setmyState] = useState('content');

0. 스테이트 문법 언제 사용할까?

변수와 스테이트의 가장 큰 차이는 __ 입니다. 일반 변수는, 그 값이 변경되더라도 현재 출력중인 HTML 문서에 실시간으로 반영되지 않습니다. 수동으로 문서를 새로고침 하거나 변수의 변경된 값을 반영해 줄 함수를 따로 만들어 사용해야만 합니다.

반면에 스테이트는 그 값이 변경될 때마다 현재 출력중인 HTML 문서를 자동으로 재렌더링 하여 변경된 값을 반영해줍니다.

따라서 자주 변경이 필요하거나 빠르게 변경이 필요한 값을 저장할 때 일반변수보다는 스테이트를 활용하는 것이 좋습니다.

1. useState 훅 import 하기

2. 스테이트 정의하기

3. 스테이트 변경함수 정의하기

[React] Element

Fri, 30 Dec 2022 05:47:41 GMT

[React] Props 사용하기

Thu, 29 Dec 2022 12:03:23 GMT

1. Props란?

props는 읽기 전용 입니다.

2. Props 사용방법

function sum(a, b) {
  return a + b;
}

function withdraw(account, amount) {
  account.total -= amount;
}

[React] 새 프로젝트 생성하기

Sat, 24 Dec 2022 14:02:16 GMT

1분 요약

원하는 경로에 새로운 폴더를 만드세요.

만든 폴더를 shift + 오른쪽 클릭하세요.

여기에 PwoerShell 창 열기를 클릭해 터미널을 켜세요.

터미널에 npx create-react-app app_name 입력하세요!

1. Node.js 설치하기

https://nodejs.org/ko/

위 링크에 방문하면 LTS 버전과 최신버전을 다운로드해서 설치할 수 있습니다. 안정적이고 신뢰도가 높은 LTS 버전을 추천합니다.

2. VS Code 설치하기

https://code.visualstudio.com/

Visual Studio Code는 코드를 편집하는 작업을 편리하게 만들어주는 편집기입니다. 위 링크에 방문하여 Visual Studio Code의 최신 안정화 버전을 다운로드 할 수 있습니다.

3. 새 React 프로젝트 생성하기

a. 새 폴더 만들기

React 프로젝트를 생성하고 싶은 경로에 아무이름이나 붙여서 폴더를 하나 만들어 주세요.

폴더 경로에 한글이 들어있으면 작업중에 충돌을 일으키는 경우가 생길 수 있으니 폴더명을 가급적 영문으로 작성하는 것을 추천합니다.

b. 터미널 켜기

방금 만든 폴더를 shift + 우클릭 하면 여기에 PowerShell 창 열기가 있습니다. 클릭하면 window 터미널이 실행됩니다.

c. React 프로젝트 생성 명령어 입력하기

실행된 터미널에 아래 명령어를 입력하세요. app_name 부분은 내가 원하는 이름으로 바꾸어 입력하면 됩니다.

대소문자를 구별하고, 띄어쓰기 공백도 중요하니 오타가 없도록 주의해 주세요.

npx create-react-app app_name

프로젝트 생성에는 1~2분 정도 시간이 소요됩니다.

d. 프로젝트 생성 성공

화면 아래쪽에 Happy hacking! 이라는 문구가 뜨면 새 React 프로젝트 생성에 성공한 것입니다.

4. VS Code에서 React 프로젝트 열기

a. VS Code를 켜고 폴더 열기

VS Code를 실행하고 화면 상단 '파일(F)' 탭에서 '폴더 열기'를 선택합니다.

방금 React 프로젝트를 생성했던 폴더를 찾아 열면 React 프로젝트를 VS Code에서 편집할 수 있도록 작업공간을 연 것입니다.

[React] 컴포넌트 생성하기

Sat, 24 Dec 2022 13:33:42 GMT

React 컴포넌트 생성하기

React에서는 어플리케이션을 이루는 기본 단위로 '컴포넌트'를 사용합니다.

컴포넌트는 입력받은 데이터(Props)와 뷰(View)에 따라서 알맞은 DOM Node를 출력하는 함수입니다.

아래 두 블럭의 코드는 표현 방식이 서로 다르지만 완전히 동일한 컴포넌트를 출력합니다.

개인적으로는 함수형 컴포넌트가 보기에 깔끔한 것 같은데, 바닐라 자바스크립트에 더 익숙한 분들이라면 클래스형 컴포넌트를 더 선호하시는 것 같습니다.

구글링을 해보면 두 형태 모두 자주 사용되니 두 가지 방식 모두 살펴보고 익숙해지는 것이 좋겠습니다.

1. 클래스형 컴포넌트


class Welcome extends React.Component {
  render() {
    return Hello, {this.props.name};
  }
}

2. 함수형 컴포넌트


function Welcome(props) {
  return Hello, {props.name};
}

[Mac] Mac OS 에서 백틱(`) 입력하는 방법

Fri, 23 Dec 2022 02:07:36 GMT

맥 OS에서 백틱( ` ) 문자를 입력하는 방법은 다음과 같습니다.

한글 입력 상태일 때 option + ₩

영어 입력 상태일 때 ₩ 키를 누르면 바로 `입력이 가능합니다.

[React] React란?

Fri, 23 Dec 2022 01:43:44 GMT

1분 요약

React 는 '컴포넌트'라는 모듈을 기본단위로 사용해서 HTML 요소들을 관리하고 동적으로 변화하도록 조작할 수 있는 JavaScript 라이브러리 입니다.

1. React의 탄생 배경

HTML과 CSS, JavaScript로 웹 서비스를 개발하다보면 몇 가지 난관에 이르게 됩니다.

우선 HTML, CSS, JavaScript 각각의 문법이 서로 다르기 때문에 익히는 것이 꽤 번거롭고 모두 능숙하게 다루게 되기까지는 상당한 시간이 소요됩니다.

더욱 큰 문제는 웹 서비스의 기능이 다양하고 많아질수록, 특히 상호작용이 필요한 UI가 많이 추가될수록 관리해야할 데이터나 변수, 기타 구조적 요소들이 기하급수적으로 늘어난다는 것입니다.

게다가 그러한 작업들이 효율적으로 이루어지지 못한다면 로딩 시간이 길어진다거나 정상적인 작동을 하지 못하는 등의 문제로 곧장 이어집니다. 웹 사이트의 성능을 전혀 장담할 수 없게 되는 것입니다.

HTML 5, CSS 3, JavaScript ES6 기반의 웹 표준이 정착되지 않았던 시기에는 HTML에 그때그때 커스텀 태그를 만들어 도입하거나 악명높은 액티브x 플러그인을 사용해서 문제를 해결하고자 했습니다. 물론 그러한 방식의 접근은 득보다는 실이 훨씬 많았기 때문에 결과적으로 실패하고 말았습니다.

2. React란?

이후로 웹 표준이 정착되고 표준을 준수하는 여러 가지 방식의 JavaScript 라이브러리들이 새롭게 등장하면서 중복되는 코드와 태그를 줄이고 HTML, CSS, JavaScript 사이의 장벽을 허물기 위한 다양한 시도들이 나타났습니다.

그중에서도 React 는 '컴포넌트'라는 모듈을 기본단위로 사용해서 HTML 요소들을 관리하고 동적으로 변화하도록 조작할 수 있는 JavaScript 프레임워크 입니다.

또, React를 사용하여 작성된 웹 페이지는 HTML에 상호작용이나 변화가 필요할 경우 페이지 전체를 다시 렌더링 하지 않고 변화한 부분만 선택적으로 다시 렌더링합니다. 따라서 페이지 로딩 속도를 향상시킬 수 있고 웹 페이지의 부드러운 동작을 가능하게 해줍니다.

3. React 학습하기

[JavaScript] 함수 (function)

Fri, 23 Dec 2022 01:36:51 GMT

1. 함수란?

코드를 작성하는 과정에서, 거의 비슷하거나 완전히 같은 내용이 여러 번 되풀이되어 쓰이는 경우가 있습니다.

alert('안녕하세요, Michael!');
alert('Hello, Michael!');
alert('こんにちは, Michael!');
alert('Hola, Michael!');

alert('안녕하세요, Christine!');
alert('Hello, Christine!');
alert('こんにちは, Christine!');
alert('Hola, Christine!');

sayHello('Michael');
sayHello('Christine');

2. 함수 선언하기

function sayHello(userName){
    alert('안녕하세요, ' + userName);
    alert('Hello, ' + userName);
    alert('こんにちは, ' + userName);
    alert('Hola, ' + userName);
}

3. 매개변수

4. 지역변수와 전역변수

5. 기본값

6. 반환값

7. 함수 이름짓기

[JavaScript] 자료형 (data type)

Wed, 21 Dec 2022 14:08:56 GMT

변수나 상수는 자료를 저장할 수 있는 공간이라는 것을 기억하시나요? (변수와 상수 링크 참고.) 그렇다면 실제로 자료를 저장하고 불러내어 사용할 수 있어야 하겠습니다. 변수나 상수에 저장할 수 있는 자료에는 셀 수 없이 많은 유형이 있습니다. 새로운 유형을 만들어 낼 수도 있지요. 그 중에 가장 단순하고 자주 사용되는 기본 자료형에는 아래와 같은 것들이 있습니다.