# LumirEditor **이미지 전용** BlockNote 기반 Rich Text 에디터 [![npm version](https://img.shields.io/npm/v/@lumir-company/editor.svg)](https://www.npmjs.com/package/@lumir-company/editor) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) > 이미지 업로드에 최적화된 경량 에디터. S3 업로드, 파일명 커스터마이징, 로딩 스피너 내장. --- ## 목차 - [특징](#특징) - [빠른 시작](#빠른-시작) - [이미지 업로드](#이미지-업로드) - [S3 업로드 설정](#1-s3-업로드-권장) - [파일명 커스터마이징](#파일명-커스터마이징) - [커스텀 업로더](#2-커스텀-업로더) - [동영상 업로드 및 임베딩](#동영상-업로드-및-임베딩) - [업로드 진행률 표시](#업로드-진행률-표시-이미지동영상-공통) - [이미지·동영상 업로드 상세 가이드](#이미지동영상-업로드-상세-가이드) - [이미지·비디오 삭제](#이미지비디오-삭제) - [테이블](#테이블) - [글자 크기](#글자-크기) - [HTML 미리보기](#html-미리보기) - [Placeholder](#placeholder) - [링크 프리뷰](#링크-프리뷰) - [Props API](#props-api) - [사용 예제](#사용-예제) - [스타일링](#스타일링) - [트러블슈팅](#트러블슈팅) --- ## 특징 | 특징 | 설명 | | ----------------------- | -------------------------------------------------------------------------------- | | **이미지 전용** | 이미지 업로드/드래그앤드롭 기본 지원 (비디오는 `allowVideoUpload`로 옵션 활성화) | | **HTML 미리보기** | HTML 파일을 드래그 앤 드롭하여 iframe으로 미리보기 | | **S3 연동** | Presigned URL 기반 S3 업로드 내장 | | **파일명 커스터마이징** | 업로드 파일명 변경 콜백 + UUID 자동 추가 지원 | | **로딩 스피너** | 이미지 업로드 중 자동 스피너 표시 | | **테이블** | Notion 스타일 행·열·셀 grip 핸들, 셀 배경색, Excel 셀 붙여넣기 지원 | | **글자 크기** | 인라인 글자 크기 변경 (프리셋 8단계 + 기본), 구버전 호환 직렬화 | | **성능 최적화** | 애니메이션 비활성화로 빠른 렌더링 | | **TypeScript** | 완전한 타입 안전성 | | **테마 지원** | 라이트/다크 테마 및 커스텀 테마 | ### 지원 이미지 형식 ``` PNG, JPEG/JPG, GIF, WebP, BMP ``` --- ## 빠른 시작 ### 1. 설치 ```bash npm install @lumir-company/editor # 또는 yarn add @lumir-company/editor ``` **필수 Peer Dependencies:** - `react` >= 18.0.0 - `react-dom` >= 18.0.0 ### 2. 기본 사용 ```tsx import { LumirEditor } from "@lumir-company/editor"; import "@lumir-company/editor/style.css"; // 필수! export default function App() { return (
console.log(blocks)} />
); } ``` > **중요**: `style.css`를 임포트하지 않으면 에디터가 정상 작동하지 않습니다. ### 3. Next.js에서 사용 ```tsx "use client"; import dynamic from "next/dynamic"; import "@lumir-company/editor/style.css"; // SSR 비활성화 필수 const LumirEditor = dynamic( () => import("@lumir-company/editor").then((m) => ({ default: m.LumirEditor })), { ssr: false }, ); export default function EditorPage() { return (
); } ``` --- ## 이미지 업로드 ### 1. S3 업로드 (권장) Presigned URL을 사용한 안전한 S3 업로드 방식입니다. ```tsx ``` #### S3 파일 저장 경로 ``` {env}/{path}/{filename} 예시: production/blog/images/my-photo.png ``` #### API 엔드포인트 응답 형식 서버는 다음 형식으로 응답해야 합니다: ```json { "presignedUrl": "https://s3.amazonaws.com/bucket/upload-url", "publicUrl": "https://cdn.example.com/production/blog/images/my-photo.png" } ``` 클라이언트는 `apiEndpoint?key={파일키}&contentType={MIME}` 형태로 GET 요청을 보내고, 서버는 위 형식으로 JSON을 반환하면 됩니다. #### S3 Presigned URL API 구현 예시 **Next.js (App Router)** 파일: `app/api/s3/presigned/route.ts` ```typescript import { NextRequest, NextResponse } from "next/server"; import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3"; import { getSignedUrl } from "@aws-sdk/s3-request-presigner"; const s3 = new S3Client({ region: process.env.AWS_REGION!, credentials: { accessKeyId: process.env.AWS_ACCESS_KEY_ID!, secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!, }, }); export async function GET(req: NextRequest) { const { searchParams } = new URL(req.url); const key = searchParams.get("key"); const contentType = searchParams.get("contentType"); if (!key) { return NextResponse.json({ error: "key is required" }, { status: 400 }); } const command = new PutObjectCommand({ Bucket: process.env.AWS_S3_BUCKET!, Key: key, ContentType: contentType || "application/octet-stream", }); const presignedUrl = await getSignedUrl(s3, command, { expiresIn: 60 }); const publicUrl = `https://${process.env.AWS_S3_BUCKET}.s3.${process.env.AWS_REGION}.amazonaws.com/${key}`; return NextResponse.json({ presignedUrl, publicUrl, key }); } ``` 필요한 환경 변수: `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_S3_BUCKET` **Next.js가 아닌 프로젝트에서 사용하기** 동일하게 **GET** 요청으로 `key`, `contentType` 쿼리 파라미터를 받아 `presignedUrl`, `publicUrl`을 JSON으로 반환하는 엔드포인트를 구현하면 됩니다. - **Express (Node.js)** ```javascript const express = require("express"); const { S3Client, PutObjectCommand } = require("@aws-sdk/client-s3"); const { getSignedUrl } = require("@aws-sdk/s3-request-presigner"); const s3 = new S3Client({ region: process.env.AWS_REGION, credentials: { accessKeyId: process.env.AWS_ACCESS_KEY_ID, secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY, }, }); app.get("/api/s3/presigned", async (req, res) => { const key = req.query.key; const contentType = req.query.contentType || "application/octet-stream"; if (!key) { return res.status(400).json({ error: "key is required" }); } const command = new PutObjectCommand({ Bucket: process.env.AWS_S3_BUCKET, Key: key, ContentType: contentType, }); const presignedUrl = await getSignedUrl(s3, command, { expiresIn: 60 }); const publicUrl = `https://${process.env.AWS_S3_BUCKET}.s3.${process.env.AWS_REGION}.amazonaws.com/${key}`; res.json({ presignedUrl, publicUrl, key }); }); ``` 에디터 사용 시 `apiEndpoint`만 해당 서버 주소로 맞추면 됩니다. ```tsx ``` - **Remix / SvelteKit / 기타 프레임워크** GET 라우트에서 `key`, `contentType`을 받아 `@aws-sdk/client-s3`의 `PutObjectCommand`와 `@aws-sdk/s3-request-presigner`의 `getSignedUrl`로 presigned URL을 생성한 뒤, `{ presignedUrl, publicUrl, key }` 형태로 JSON 응답하면 동일하게 사용할 수 있습니다. CORS가 필요한 경우 해당 도메인을 허용해 두세요. --- ### 파일명 커스터마이징 여러 이미지를 동시에 업로드할 때 파일명 중복을 방지하고 관리하기 쉽게 만드는 기능입니다. > **참고**: 기본적으로 확장자는 자동으로 붙습니다. `preserveExtension: false`로 설정하면 확장자를 붙이지 않습니다. #### 옵션 1: UUID 자동 추가 ```tsx ``` **결과:** ``` 원본: photo.png 업로드: photo_550e8400-e29b-41d4-a716-446655440000.png ``` #### 옵션 2: 파일명 변환 콜백 ```tsx { // nameWithoutExt는 확장자가 제거된 파일명 (예: "photo") // 확장자는 자동으로 붙습니다 const userId = getCurrentUserId(); return `${userId}_${nameWithoutExt}`; }, }} /> ``` **결과:** ``` 원본: photo.png → nameWithoutExt: "photo" → 변환 후: "user123_photo" → 최종: user123_photo.png ``` #### 옵션 3: 조합 사용 (권장) ```tsx `user123_${nameWithoutExt}`, appendUUID: true, // 변환 후 UUID 추가 }} /> ``` **결과:** ``` 원본: photo.png → nameWithoutExt: "photo" 1. fileNameTransform 적용: "user123_photo" 2. appendUUID 적용: "user123_photo_550e8400-e29b-41d4" 3. 확장자 붙이기: user123_photo_550e8400-e29b-41d4.png ``` #### 실전 예제: 타임스탬프 + UUID ```tsx function MyEditor() { return ( { // nameWithoutExt는 이미 확장자가 제거됨 const timestamp = new Date().toISOString().split("T")[0]; // 2024-01-15 return `${timestamp}_${nameWithoutExt}`; }, appendUUID: true, }} /> ); } ``` **결과:** ``` 원본: photo.png → nameWithoutExt: "photo" 1. fileNameTransform: "2024-01-15_photo" 2. appendUUID: "2024-01-15_photo_550e8400-e29b-41d4" 3. 확장자 붙이기: 2024-01-15_photo_550e8400-e29b-41d4.png ``` #### 옵션 4: 확장자 제거 (preserveExtension: false) ```tsx `${nameWithoutExt}_custom`, preserveExtension: false, // 확장자 안 붙임 }} /> ``` **결과:** ``` 원본: photo.png → nameWithoutExt: "photo" → 변환 후: "photo_custom" → 최종: photo_custom (확장자 없음) ``` **사용 사례**: WebP 변환 등 서버에서 확장자를 변경하는 경우 ```tsx fileNameTransform: (nameWithoutExt) => `${nameWithoutExt}.webp`, preserveExtension: false, ``` --- ### 2. 커스텀 업로더 자체 업로드 로직을 사용할 때: ```tsx { const formData = new FormData(); formData.append("image", file); const response = await fetch("/api/upload", { method: "POST", body: formData, }); const { url } = await response.json(); return url; // 업로드된 이미지 URL 반환 }} /> ``` ### 3. 헬퍼 함수 사용 ```tsx import { createS3Uploader } from "@lumir-company/editor"; const s3Uploader = createS3Uploader({ apiEndpoint: "/api/s3/presigned", env: "production", path: "images", appendUUID: true, }); // 에디터에 적용 ; // 또는 별도로 사용 const imageUrl = await s3Uploader(imageFile); ``` ### 업로드 우선순위 1. `uploadFile` prop이 있으면 우선 사용 2. `uploadFile` 없고 `s3Upload`가 있으면 S3 업로드 사용 3. 둘 다 없으면 업로드 실패 --- ## 동영상 업로드 및 임베딩 `allowVideoUpload={true}`로 설정하면 동영상 업로드와 에디터 내 재생이 가능합니다. S3/`uploadFile`은 이미지와 동일한 설정을 사용하며, 동영상은 최대 100MB까지 허용됩니다. ### 동영상 업로드 활성화 ```tsx ``` - **지원 형식**: MP4, WebM, OGG - **삽입 경로**: 붙여넣기, 드래그 앤 드롭, 슬래시 메뉴("Video"), FloatingMenu 이미지/동영상 버튼 ### 업로드 진행률 표시 (이미지·동영상 공통) S3 업로드 시 `s3Upload.onProgress` 콜백을 지정하면 업로드 진행률(0~100%)을 받을 수 있습니다. 에디터는 내부적으로 이 값을 사용해 업로드 중 툴바에 **"n%"** 를 표시합니다. 동영상처럼 대용량 파일은 브라우저가 `progress` 이벤트를 자주 보내지 않을 수 있어, 내부적으로 **보간 로직**을 적용해 0→100만 보이지 않고 중간 진행률이 부드럽게 갱신되도록 했습니다. ```tsx { console.log(`업로드 진행률: ${percent}%`); // 에디터 기본 UI에 이미 표시되며, 필요 시 자체 프로그레스 바 등에 연동 가능 }, }} /> ``` - **동작**: S3 PUT 요청 시에만 호출됩니다. Presigned URL 요청 단계에서는 호출되지 않습니다. - **표시**: `onProgress`를 넘기면 에디터 툴바에 `n%`가 자동 표시되며, 업로드 완료 시 숨겨집니다. ### 데이터 내부 동영상 임베딩 동영상 블록은 `initialContent` / `onContentChange`에 포함됩니다. 저장 시 `{ type: "video", props: { url: "..." } }` 형태로 블록이 유지됩니다. - **재생**: 화면에서 동영상을 재생하려면 `allowVideoUpload={true}`로 두어야 합니다. 이렇게 해야 video 확장이 활성화되어 BlockNote 기본 플레이어가 렌더링됩니다. - `allowVideoUpload={false}`인 상태에서 initialContent에 video 블록만 넣으면 데이터는 보존되지만, 재생 UI는 비활성화된 확장 때문에 표시되지 않을 수 있습니다. - **지원 URL**: 비디오 블록의 `url`은 **직접 재생 가능한 비디오 파일 URL**만 지원합니다(예: S3에 업로드된 `.mp4`, `.webm`, `.ogg`). YouTube·Vimeo 등 스트리밍 페이지 URL(`youtube.com/watch?v=...` 등)은 `