Strapi는 Node.js 기반의 오픈소스 헤드리스 CMS로, API, 데이터베이스, 배포에 대한 완전한 제어 권한을 제공합니다. 다른 호스팅형 CMS 플랫폼처럼 남의 인프라에 접근하는 것과 달리, Strapi는 당신의 서버에서 실행되며 콘텐츠 스키마로부터 REST 및 GraphQL 엔드포인트를 생성하고, 일반 JavaScript나 TypeScript로 백엔드의 모든 계층을 커스터마이징할 수 있습니다.
이 가이드는 첫 번째 npx create-strapi 명령부터 Railway나 Strapi Cloud에서의 프로덕션 배포까지 Strapi 5를 다룹니다. 모든 코드 예제는 복사해서 바로 사용할 수 있으며, Strapi 5.x를 대상으로 검증되었습니다.
Strapi란 무엇이고 어떻게 작동하나요?
Strapi는 자체 호스팅 방식의 API 중심 콘텐츠 관리 시스템으로, 콘텐츠 백엔드와 프론트엔드를 분리합니다. 시각적 빌더나 코드를 통해 콘텐츠 스키마를 정의하면, Strapi는 자동으로 CRUD API 엔드포인트(REST와 GraphQL 모두)를 생성하여 어떤 프론트엔드 프레임워크에서든 사용할 수 있습니다. 관리자 패널은 React 기반 UI로, 콘텐츠 편집자가 코드에 손대지 않고도 항목을 만들고 관리할 수 있으며, 공식 Strapi 문서를 참고하면 됩니다.
헤드리스 CMS vs 전통적인 CMS
WordPress 같은 전통적인 CMS는 콘텐츠와 표현 계층을 함께 묶습니다. 블로그 글, 페이지, 미디어가 모두 방문자에게 HTML을 렌더링하는 동일한 시스템 내에 존재합니다. 이는 콘텐츠가 모바일 앱, 마케팅 마이크로사이트, 문서 포털에 동시에 필요할 때까지는 잘 작동합니다.
헤드리스 CMS는 프론트엔드를 완전히 제거합니다. Strapi는 콘텐츠를 저장하고 API 엔드포인트를 통해 JSON으로 제공합니다. Next.js 사이트, React Native 앱, IoT 대시보드가 모두 동일한 Strapi 백엔드에서 데이터를 가져옵니다. 단 하나의 정보 출처를 가지면서도 여러 소비자에게 제공할 수 있습니다.
Strapi 외에 다른 옵션들을 평가하고 있다면, 헤드리스 CMS 비교 가이드에서 주요 플랫폼들을 나란히 비교할 수 있습니다.
Strapi의 아키텍처
Strapi의 스택은 단순합니다: Node.js 서버가 데이터베이스(PostgreSQL, MySQL, SQLite)와 프론트엔드 애플리케이션 사이에 위치합니다. 관리자 패널(React 싱글페이지 애플리케이션)은 프론트엔드가 사용하는 동일한 API에 연결되지만 상위 권한을 가집니다.
흐름은 다음과 같습니다: 데이터베이스가 콘텐츠를 저장합니다. Strapi의 ORM 계층(Knex.js 기반)이 쿼리합니다. API 계층이 REST 및 GraphQL 엔드포인트를 노출합니다. 프론트엔드(Next.js, Nuxt, Astro, Gatsby 또는 모바일 앱 등)가 이 엔드포인트에서 JSON을 가져옵니다. Strapi 자체는 최종 사용자에게 HTML을 렌더링하지 않습니다.
Strapi GitHub 저장소는 65,000개 이상의 별을 받았으며, 플랫폼에서 가장 인기 있는 오픈소스 CMS 프로젝트 중 하나입니다.
Strapi 5의 새로운 기능은?
Strapi 5는 Entity Service API를 새로운 Document Service API로 대체하고, Webpack에서 Vite로 전환하며, 새 프로젝트의 기본 언어로 TypeScript를 도입하는 주요 재작성 버전입니다. 이는 점진적 업데이트가 아니라 내부 아키텍처가 크게 변경되었으며, Strapi 5 개요 페이지에서 자세히 확인할 수 있습니다.
Strapi 5 개발자 변경 로그에 따르면 개발자들에게 가장 중요한 변경 사항은 다음과 같습니다:
- Document Service API가 Entity Service API를 대체 -- 더 깔끔한 메서드 시그니처, 향상된 TypeScript 타입, CRUD 작업을 위한 통합 인터페이스
- Draft & Publish 재작성 -- 관리자 패널의 이원 탭 시스템으로 초안과 발행된 콘텐츠 상태 분리
- 콘텐츠 이력 -- 관리자에서 직접 항목의 이전 버전을 보고 복원
- 미리보기 기능 -- 발행 전에 실제 프론트엔드에서 콘텐츠를 미리 볼 수 있으며, 콘텐츠 타입별로 설정 가능
- Vite가 Webpack을 대체 -- 관리자 패널 빌드가 눈에 띄게 빨라짐(약 60% 빌드 시간 단축 확인)
- TypeScript 우선 접근 -- 새 프로젝트는 기본적으로 TypeScript로 스캐폴딩됨
- AI 콘텐츠 타입 빌더 -- 자연어 설명이나 Figma 디자인에서 콘텐츠 스키마 생성. 2026년의 새로운 기능으로 다른 헤드리스 CMS에서는 아직 제공되지 않음
- 단순화된 API 응답 -- REST와 GraphQL 모두를 위한 평탄한 JSON 구조
- 새로운 플러그인 SDK -- Strapi 플러그인 빌드 및 배포를 위한 간소화된 API
Strapi 5 설치 및 설정 방법
Strapi 5 프로젝트 설정에는 약 2분이 소요됩니다. Node.js 18 이상, npm, yarn 또는 pnpm이 필요합니다. Strapi는 하나의 명령으로 관리자 패널, 데이터베이스 연결 및 API 계층을 갖춘 완전한 프로젝트를 생성하며, Strapi 빠른 시작 가이드에서 자세히 확인할 수 있습니다.
전제 조건
- Node.js 18 이상(권장: 20 LTS)
- npm 6 이상, yarn 또는 pnpm
- 데이터베이스: 개발 환경에서는 SQLite가 바로 사용 가능하며, 프로덕션에서는 PostgreSQL 사용
첫 번째 프로젝트 생성
Strapi는 http://localhost:1337 에서 시작합니다. 처음 방문할 때 관리자 계정을 만들도록 요청합니다. 그 후에는 관리자 패널에서 콘텐츠 타입을 구축할 준비가 됩니다.
프로젝트 구조 개요
각 콘텐츠 타입은 스키마, 컨트롤러, 라우트, 서비스 파일과 함께 src/api/ 아래의 자체 폴더를 갖습니다. Strapi는 관리자 패널을 통해 콘텐츠 타입을 생성할 때 이들을 자동으로 생성하지만, 수동으로 만들 수도 있습니다.
콘텐츠 타입 구축 및 콘텐츠 관리
콘텐츠 타입은 Strapi의 핵심으로, 데이터 스키마를 정의하고 자동으로 API 엔드포인트, 관리자 패널 폼, 데이터베이스 테이블을 생성합니다. Strapi는 두 가지 주요 타입을 지원합니다: 컬렉션 타입(블로그 글이나 상품처럼 많은 항목이 있는 경우)과 싱글 타입(홈페이지나 사이트 설정처럼 항목이 하나만 존재하는 경우).
콘텐츠 타입 빌더 안내
Strapi 관리자 패널의 콘텐츠 타입 빌더를 사용하면 시각적으로 스키마를 정의할 수 있습니다. 필드 타입(텍스트, 리치 텍스트, 미디어, 숫자, 부울, 관계, 컴포넌트, 동적 존, JSON 등)을 선택하면 Strapi가 스키마 파일을 작성합니다.
Article 콘텐츠 타입 스키마가 내부적으로 어떻게 보이는지 예를 들면 다음과 같습니다:
새로운 AI 콘텐츠 타입 빌더를 사용하여 "제목, 슬러그, 리치 텍스트 콘텐츠, 커버 이미지, 카테고리가 있는 블로그가 필요합니다" 같은 일반 영어 설명에서 스키마를 생성할 수도 있습니다. Strapi가 스키마 JSON을 생성하고 데이터베이스 테이블을 만듭니다. 프로토타이핑에 정말 유용합니다.
컴포넌트 및 동적 존
컴포넌트는 재사용 가능한 필드 그룹입니다. React 컴포넌트처럼 생각하되, 콘텐츠 구조를 위한 것입니다. metaTitle, metaDescription, canonicalUrl 필드를 가진 "SEO" 컴포넌트는 어떤 콘텐츠 타입에나 첨부될 수 있습니다.
동적 존은 한 단계 더 나아갑니다 -- 콘텐츠 편집자가 컴포넌트 목록에서 선택하여 유연한 페이지 레이아웃을 구축할 수 있습니다. 랜딩 페이지에 Hero 컴포넌트, 그 다음 Features Grid, 마지막으로 Testimonials Slider가 있을 수 있으며, 모두 편집자가 선택하고 정렬할 수 있습니다. 이 패턴은 모든 페이지가 다른 구조를 가진 마케팅 사이트에서 인기 있습니다.
Draft & Publish로 콘텐츠 관리
Strapi 5는 Draft & Publish 시스템을 전면 개편했습니다. 단일 토글 대신, 콘텐츠 관리자에서 이제 두 개의 분리된 탭을 얻습니다 -- 하나는 초안용, 하나는 발행된 콘텐츠용입니다. 편집자는 라이브 콘텐츠에 영향을 미치지 않고 자유롭게 초안을 수정할 수 있습니다. 준비가 되면 발행하고 초안이 새로운 발행 버전이 됩니다. 콘텐츠 이력을 통해 뭔가 잘못되었을 때 이전 상태로 롤백할 수 있습니다.
Strapi API 작업 (REST 및 GraphQL)
Strapi는 만드는 모든 콘텐츠 타입에 대해 REST 및 GraphQL 엔드포인트를 자동으로 생성합니다. REST API는 즉시 사용 가능하며 설정이 필요 없습니다. GraphQL은 기본 플러그인 활성화가 필요하지만 약 30초 정도 걸립니다. 두 API 모두 필터링, 정렬, 페이지 나누기, 필드 선택, 관계 포함을 지원하며, Strapi REST API 문서에서 확인할 수 있습니다.
REST API 쿼리
모든 컬렉션 타입은 /api/{pluralName}에서 엔드포인트를 얻습니다. 필터와 관계 포함으로 기사를 가져오는 방법은 다음과 같습니다:
Strapi 5는 응답 형식을 평탄하게 만들었습니다. v4에서는 data.attributes.title을 통해 탐색했습니다. v5에서는 그냥 data.title입니다. 작은 변화이지만 큰 삶의 질 개선입니다.
...