테마와 템플릿을 넘어 Shopify를 확장하고자 하는 웹 개발자라면, 커스텀 Shopify 앱을 구축하는 것은 배울 수 있는 가장 가치 있는 기술 중 하나입니다. Shopify 앱을 통해 상인은 워크플로우를 자동화하고, 제3자 서비스를 통합하며, 관리자 경험을 맞춤 설정하고, 완전히 새로운 기능을 생성할 수 있습니다.

이 가이드에서는 첫 번째 Shopify 앱을 구축하기 위한 아키텍처, 설정 및 개발 프로세스를 단계별로 살펴보겠습니다.

Shopify 앱이란 무엇인가?

Shopify 앱은 Shopify Admin API, Storefront API 또는 웹훅 (webhooks)을 통해 Shopify 스토어와 상호 작용하는 소프트웨어입니다.

앱의 종류는 다음과 같습니다:

• Public Apps (공개 앱) – Shopify App Store를 통해 배포됩니다.
• Custom Apps (커스텀 앱) – 단일 상인을 위해 구축됩니다.
• Private/Internal Apps (프라이빗/내부 앱) – 자체 조직 내에서 사용됩니다 (레거시 유스케이스).

대부분의 에이전시와 SaaS 기업은 커스텀 (custom) 또는 공개 (public) 앱을 구축합니다.

기술 스택 (Tech Stack)

현대적인 Shopify 앱은 일반적으로 다음을 사용합니다:

• Node.js
• React
• Remix 또는 Next.js
• Shopify App Bridge
• Polaris Design System
• Prisma ORM
• PostgreSQL
• Shopify Admin GraphQL API

Ruby와 PHP가 여전히 지원되기는 하지만, Shopify는 현재 현대적인 JavaScript 프레임워크를 권장합니다.

사전 요구 사항 (Prerequisites)

시작하기 전에 다음이 필요합니다:

• Shopify Partner 계정
• 개발 스토어 (development store)
• Node.js (최신 LTS)
• Git
• Shopify CLI

Shopify CLI 설치:

npm install -g @shopify/cli @shopify/app

설치 확인:

shopify version

앱 생성하기

Shopify CLI를 사용하여 새로운 애플리케이션을 생성합니다.

shopify app init

다음 항목을 선택하세요:

• Remix
• JavaScript 또는 TypeScript
• Embedded App (임베디드 앱)

그 다음 의존성(dependencies)을 설치합니다:

npm install

개발 서버 실행:

shopify app dev

CLI는 로컬 개발을 위한 보안 터널을 자동으로 생성합니다.

폴더 구조 이해하기

전형적인 프로젝트 구조는 다음과 같습니다:

app/
routes/
components/
...

중요한 폴더는 다음과 같습니다:

• routes/ → 앱 페이지 (App pages)
• components/ → React 컴포넌트 (React components)
• prisma/ → 데이터베이스 스키마 (Database schema)
• shopify.server.js → 인증 및 API 설정 (Authentication and API setup)

인증 (Authentication)

모든 임베디드 앱 (Embedded app)은 OAuth를 사용하여 상인 (Merchants)을 인증해야 합니다.

Shopify CLI가 이를 자동으로 구성합니다.

예시:

await authenticate.admin(request);

인증이 완료되면, 앱은 Admin API 클라이언트 (Admin API client)를 받게 됩니다.

Shopify GraphQL API 호출하기

제품 가져오기:

const response = await admin.graphql(`
{
  products(first:5){
...

GraphQL은 여러 번의 REST API 요청을 보내는 것보다 훨씬 빠릅니다.

Polaris 컴포넌트 사용하기

Shopify는 일관된 UI를 위해 Polaris 사용을 권장합니다.

예시:

<Card>
  <Text variant="headingLg">
    Dashboard
...

장점은 다음과 같습니다:

• 접근성 (Accessibility)
• Shopify 네이티브 디자인 (Native Shopify appearance)
• 반응형 레이아웃 (Responsive layouts)
• 더 빠른 개발 속도

웹훅 (Webhooks) 처리하기

웹훅은 무언가 변경될 때마다 앱에 알림을 보냅니다.

예시:

• 제품 생성됨 (Product Created)
• 주문 결제됨 (Order Paid)
• 고객 정보 업데이트됨 (Customer Updated)
• 재고 변경됨 (Inventory Changed)

웹훅 등록:

await shopify.registerWebhooks();

예시 핸들러 (Handler):

export async function action({ request }) {
   const payload = await request.json();

...

데이터 저장하기

대부분의 앱은 자체 데이터베이스가 필요합니다.

인기 있는 선택지:

• PostgreSQL
• MySQL
• PlanetScale
• Supabase

Prisma는 Shopify 앱을 위한 훌륭한 ORM입니다.

예시 스키마 (Schema):

model Store {

  id String @id
...

관리자 기능 구축하기

유용한 기능에는 다음이 포함됩니다:

• 제품 동기화 (Product synchronisation)
• 일괄 편집 (Bulk editing)
• 분석 대시보드 (Analytics dashboards)
• 고객 세분화 (Customer segmentation)
• 재고 자동화 (Inventory automation)
• 마케팅 통합 (Marketing integrations)

각 기능은 Shopify API와 상호작용합니다.

App Bridge

App Bridge를 사용하면 임베디드 앱이 Shopify 관리자 페이지처럼 동작할 수 있습니다.

포함된 기능:

• 토스트 알림 (Toast notifications)
• 네비게이션 (Navigation)
• 로딩 인디케이터 (Loading indicators)
• 리소스 피커 (Resource picker)
• 모달 창 (Modal windows)

예시:

shopify.toast.show("Saved successfully");

배포 (Deployment)

인기 있는 호스팅 플랫폼:

• Vercel
• Railway
• Fly.io
• Render
• DigitalOcean

또한 다음 사항들이 필요합니다:

• HTTPS
• 환경 변수 (Environment variables)
• 데이터베이스 호스팅 (Database hosting)

초보자의 흔한 실수

API 속도 제한 (Rate limits) 무시

항상 요청을 배치 (Batch) 처리하고 GraphQL을 효율적으로 사용하세요.

웹훅 (Webhooks) 검증 누락

요청을 처리하기 전에 웹훅 서명 (Webhook signatures)을 반드시 확인하세요.

민감한 데이터를 안전하지 않게 저장

액세스 토큰 (Access tokens)을 프론트엔드 코드에 절대 노출하지 마세요.

REST API 과다 사용

가능한 한 GraphQL을 우선적으로 사용하세요.

웹훅 재시도 (Retries) 망각

Shopify는 실패한 웹훅을 재시도합니다. 여러분의 엔드포인트 (Endpoints)는 멱등성 (Idempotent)을 유지해야 합니다.

권장 사항 (Best Practices)

• TypeScript를 사용하세요.
• 비즈니스 로직을 라우트 (Routes)와 분리하세요.
• 비용이 많이 드는 API 호출은 캐싱 (Cache)하세요.
• 웹훅 실패를 로그 (Log)로 남기세요.
• 오래 걸리는 작업에는 백그라운드 작업 (Background jobs)을 사용하세요.
• 여러 개의 개발용 스토어 (Development stores)에서 테스트하세요.
• Shopify의 API 버전 관리 (Versioning) 일정을 준수하세요.

마치며

Shopify 앱을 구축하는 것은 단순히 API 호출 코드를 작성하는 것 그 이상입니다. 잘 설계된 앱은 안전한 인증 (Authentication), 효율적인 GraphQL 쿼리 (Queries), 반응형 인터페이스 (Interfaces), 웹훅 기반의 자동화, 그리고 확장 가능한 인프라 (Infrastructure)를 결합합니다.

고객을 위한 내부 도구를 만들든, Shopify App Store에 SaaS 제품을 출시하든, Shopify 앱 개발을 마스터하는 것은 전 세계 수백만 명의 판매자가 있는 번창하는 생태계로 향하는 문을 여는 것과 같습니다.

작은 기능부터 시작하여 판매자의 피드백을 바탕으로 반복 개선하고, 실제 비즈니스 문제를 해결하는 데 집중하세요. 훌륭한 Shopify 앱은 기능의 개수로 정의되지 않습니다. 그 앱이 전달하는 가치로 정의됩니다.

즐거운 코딩 되세요!