Strapi 5 극한의 커스텀: Quill 통합 및 멀티 테넌트 아키텍처 구현

2025년 9월, 개발자들을 위한 대규모 업데이트와 함께 “Strapi 5”가 릴리스되었습니다. Strapi 4의 데이터 구조와 완전히 결별한 이번 버전은 파괴적인 변경 사항, 완전히 개편된 다국어 API, 그리고 대폭 향상된 성능을 도입했습니다. 더욱 단순하고 강력한 도구가 되었지만, 기본 설정 중 일부는 개선의 여지가 있었습니다.

특히 기본 제공되는 “Blocks” 에디터(Lexical 기반)는 모던하지만 리치 레이아웃 디자인에 자주 요구되는 고급 테이블 편집이나 텍스트 꾸미기 기능이 부족합니다. 심지어 테이블 테두리조차 기본으로 추가할 수 없었습니다. 서구권 웹 디자인에서는 테이블 테두리를 덜 사용할지 모르지만, 구조화되고 읽기 쉬운 페이지 작성을 선호하는 일본에서는 테이블 테두리가 필수적입니다.

또한 Strapi 5에는 기본 멀티 테넌시 기능이 없습니다. 조직마다 개별 컨테이너를 가동할 수는 있지만, 테넌트별로 전용 PostgreSQL 데이터베이스를 구동하는 것은 비용이 많이 듭니다. 비용 효율적인 멀티 테넌시를 구현하기 위해 백엔드를 커스텀했습니다. 블로그 “kuro.boo”를 위해 최고의 편집 경험과 관리 효율성을 구현하고자 Strapi 5 환경을 어떻게 수정했는지 소개합니다.

1. 일본어 입력기(IME) 버그 해결

Strapi는 React 기반이어서 특정 UI 동작이 발생합니다. Strapi 5의 메인 에디터는 일본어 IME 이벤트를 처리할 때 미세한 버그가 있어, 타이핑 중 커서가 튀는 현상이 발생했습니다. macOS에서 세 가지 IME(Apple 기본 입력기, Google 일본어 입력기, Kawasemi)를 테스트했으나, 에디터가 불필요한 키 이벤트를 가로채 커서 튐 현상이 지속되었습니다. 처음에는 Zed 같은 외부 에디터에서 글을 쓴 뒤 복사해서 붙여넣어야만 했습니다. 이는 너무 번거로웠습니다.

2. 복수 이미지 업로드 처리

기사에는 텍스트와 커버 이미지 외에도 많은 이미지가 필요합니다. 처음에는 다음 플러그인을 테스트했습니다.

TipTap

TipTap은 널리 사용되고 복수 이미지를 지원하지만, 구현 과정에서 이미지 한 장과 텍스트 한 문단마다 개별 입력 블록을 추가해야 했습니다. 이는 구시대적이며 진정한 WYSIWYG 경험과는 거리가 멀어 자주 사용하는 Dropbox Paper의 매끄러운 레이아웃 툴이 그리워졌습니다.

3. Quill로의 전환

Lexical과 TipTap이 요구사항에 맞지 않아 Quill을 살펴보았습니다. v2 출시와 함께 Quill은 우수한 유연성을 보여주었습니다. WYSIWYG 기능은 유망해 보였지만 여전히 고급 테이블 기능은 자체 지원하지 않았습니다. 이를 해결하기 위해 하루 동안의 디버깅 끝에 “quill-better-table” 플러그인을 통합했습니다. 이 플러그인은 마우스 우클릭을 통한 행/열 추가 및 삭제, 셀 병합, 에디터 내부의 직접적인 셀 스타일 커스텀을 지원합니다. 중요한 점은 이러한 테이블이 표준 HTML로 저장되어 Astro 프론트엔드에서 간편하게 렌더링될 수 있다는 것입니다.

이를 통해 테이블 편집과 IME 입력 문제를 모두 해결하고 Strapi 내부에 매우 유용한 WYSIWYG 에디터 패널을 구축했습니다.

4. 드래그 앤 드롭 이미지 업로드 추가

글쓰기 흐름을 부드럽게 만들기 위해 드래그 앤 드롭 기능을 추가했습니다. 이미지를 드래그하거나 클립보드에서 붙여넣으면 Strapi 업로드 API가 자동으로 작동하여 미디어 라이브러리에 등록하고 에디터에 삽입해 줍니다. (참고: 드래그 앤 드롭 방식은 용량 초과 파일에 대해 자세한 에러 메시지를 보여주지 않으므로, 여전히 파일 크기 제한은 의식해야 합니다).

5. 스키마 기반 멀티 테넌시 구현

데이터베이스 컨테이너를 개별적으로 띄우지 않고 단일 Strapi 인스턴스에서 멀티 사이트를 관리하기 위해, 동일 데이터베이스 인스턴스 안에서 데이터베이스 스키마(DATABASE_SCHEMA)를 전환하도록 구현했습니다. 이를 통해 데이터베이스 비용을 낮게 유지하면서 테넌트별로 독립적이고 안전한 DB 환경을 구축할 수 있었습니다.

6. 로컬 우선 정적 사이트 생성(SSG) 워크플로

협업 팀에게는 CMS 서버를 24시간 구동하는 것이 이상적이지만, 개인 블로그나 업데이트 빈도가 낮은 사이트에는 불필요한 비용과 보안 리스크를 유발합니다. 따라서 배포 아키텍처를 다음과 같이 변경했습니다.

1. 글을 쓰거나 편집할 때만 로컬 Strapi 인스턴스를 실행합니다.
2. Strapi 콘텐츠를 Astro 정적 페이지로 컴파일하고 이미지를 빌드 폴더로 복사하여 이미지 링크를 업데이트하는 개발 빌드를 실행합니다.
3. 로컬 Strapi 인스턴스를 종료하고 빌드된 완전 정적 사이트를 Cloudflare Pages에 배포합니다.

이러한 설정은 공개 사이트가 완전히 Cloudflare의 에지 네트워크에서 호스팅됨을 의미합니다. 로딩 속도가 극도로 빠르고 호스팅 비용이 전혀 들지 않으며, 외부 노출형 DB로 인한 보안 리스크도 사라집니다. kuro.boo에서는 호스팅 비용이 들지 않으므로 편의상 로컬 머신에서 로컬 Strapi 인스턴스를 계속 실행하고 있습니다.

기본 설정 vs 커스텀 설정 비교:

결론

아주 작은 편집만 해도 글의 발행일이 갱신되어 예전 글이 피드 상단으로 올라가는 마이너 버그도 해결했습니다. 전용 `publishedAt` 필드를 추가하고 이를 기준으로 정렬하도록 수정했습니다. Strapi 5 소스코드를 직접 수정하는 것은 추후 업그레이드를 어렵게 만들 수 있지만, 이러한 자유로운 커스텀이야말로 헤드리스 CMS 플랫폼의 진정한 매력입니다. 덕분에 요구사항에 정확히 맞춘 편집 환경을 구성할 수 있었습니다.

출처:

・Strapi 5 문서

・Quill - 리치 텍스트 에디터

・quill-table-better (GitHub)