useEffect(() => {
    if (!isOpen || !buttonRef.current) {
      return;
    }
>
    const observer = new IntersectionObserver( // 1. 감시자 생성
      ([entry]) => { // 버튼 상태 감지
        if (!entry.isIntersecting) { // 스크롤로 버튼이 안보이면
          setIsOpen(false); // 툴팁 닫기
        }
      },
      {
        root: buttonRef.current?.closest('.overflow-y-auto'), // 기준 영역 = 스크롤 컨테이너
        threshold: 0, // 1px이라도 벗어나면 감지
      }
    );
>
    observer.observe(buttonRef.current); // 2. 감시 대상 등록 (버튼 감시 시작)
    return () => observer.disconnect(); // 3. 감시 중단 (isOpen 바뀌거나 언마운트 시 감시 중단)
  }, [isOpen]);

IntersectionObserver란?

특정 요소가 _지정한 영역(root)에 보이는지 안보이는지를 감시_하는 브라우저 API

root (스크롤 컨테이너)
┌─────────────────┐
│                 │
│  [버튼] ← 보임       │  → isIntersecting: true
│                 │
└─────────────────┘
   [버튼] ← 스크롤로 밖으로 나감 → isIntersecting: false

entry란?

observer가 감시하는 요소 하나하나의 상태 정보

const observer = new IntersectionObserver(
  (entries) => {
    // entries = 감시 중인 요소들의 상태 배열
    // observer.observe(buttonRef.current) 하나만 등록했으니
    // entries[0] = 버튼 상태
    const entry = entries[0]; // = ([entry]) 구조분해
>
    entry.isIntersecting  // 보이면 true, 안보이면 false
    entry.target          // 감시 대상 DOM 요소 (버튼)
    entry.intersectionRatio // 얼마나 보이는지 비율 (0.0 ~ 1.0)
  }
);

참고) 공식문서 - IntersectionObserver

1. 중괄호 {} → 코드 블록

.map((x) => {
  // 여러 줄 코드 가능
  const double = x * 2;
  return double;  // 반드시 return 필요
});

{} 는 “코드 블록”

return 없으면 무조건 undefined

여러 줄 쓸 때 주로 사용

2. 소괄호 () + 중괄호 {} → 객체 리터럴 반환

.map((x) => ({ value: x * 2 }))

그냥 {} 쓰면 블록으로 인식 → undefined

객체를 반환하려면 반드시 ()로 감싸야 함

❌ 잘못된 예시

.map((x) => { value: x * 2 }) // 블록으로 해석 → undefined

3. 아무 괄호 없음 → 한 줄 표현식

.map((x) => x * 2)

한 줄 계산식은 자동으로 반환(return 생략 가능)

단순한 값 변환할 때 편리

🧠 기억 꿀팁

{ } = 블록 → return 꼭 써야 함

( { } ) = 객체 → return 없이도 객체 반환

그냥 값 → return 생략 가능

yarn add xlsx-js-style

스타일 없이 엑셀 다운로드만 하려고 하면 간단히 구현 가능하다 실제로 몇 분 안걸렸다!

그때는 스타일 줄 생각을 안하고 있어서 xlsx로 진행했는데 xlsx-js-style이 xlsx 포크해서 개발된거라 api가 거의 동일하다

만약 스타일 적용 안하고 간단하게만 사용할 예정이라면 xlsx 공식문서

npm i --save https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz
>
or
>
yarn add https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz

아래는 추출 할 데이터이다.

const header = [
  '배송지 구분 번호',
  '배송지명',
  '배송지 주소',
  '수령인',
  '택배사',
  '송장번호',
  '비고',
];
>
const body = [
  {
    deliveryTypeNumber: '1',
    deliveryName: '서울',
    deliveryAddress: '서울시 강남구',
    recipient: '홍길동',
    courierCompany: 'CJ대한통운',
    trackingNumber: '1234567890',
    notes: '특별 요청 없음',
  },
  {
    deliveryTypeNumber: '2',
    deliveryName: '부산',
    deliveryAddress: '부산시 해운대구',
    recipient: '김철수',
    courierCompany: '한진택배',
    trackingNumber: '0987654321',
    notes: '빠른 배송 요청',
  },
  {
    deliveryTypeNumber: '3',
    deliveryName: '대구',
    deliveryAddress: '대구시 수성구',
    recipient: '이영희',
    courierCompany: '롯데택배',
    trackingNumber: '1122334455',
    notes: '문 앞에 놓아주세요',
  },
];

💡 사용법

기본 엑셀 추출

import { utils, WorkBook, writeFileXLSX } from 'xlsx'; // xlsx-js-style 동일
>
const ExportExcel = () => {
  const handleExport = useCallback(() => {
    const wb:WorkBook  = utils.table_to_book([...header,...body]);
    writeFileXLSX(wb, '파일명.xlsx');
  }, []);
  >
    return (
     <div className="w-120pxr">
       <Button onClick={handleExport}>Export</Button>
     </div>
  );
};
>
export default ExportExcel;

간단히는 이렇게 가능하다

시트명 커스텀 추출

만약 시트를 생성해서 시트명과 함께 파일로 추출하고 싶다면

import { utils, WorkBook, writeFileXLSX } from 'xlsx'; // xlsx-js-style 동일
>
const ExportExcel = () => {
  const handleExport = useCallback(() => {
    const ws = utils.aoa_to_sheet([...header,...body]);
    >
    const wb: WorkBook = utils.book_new();
    utils.book_append_sheet(wb, ws, '원하는 시트명');
    writeFileXLSX(wb, '파일명.xlsx');
  }, []);
  >
    return (
     <div className="w-120pxr">
       <Button onClick={handleExport}>Export</Button>
     </div>
  );
};
>
export default ExportExcel;

이렇게 시트 생성 후 파일 추출할 수도 있다.

스타일 적용

근데 스타일을 주려고 하니까 xlsx에서는 지원하지 않는게 많아서(아마 pro를 사용해야 하는 듯;)

xlsx-js-style라이브러리를 사용했다

설치방법은 최상단에 적어뒀으니까 생략하고

import { utils, WorkBook , writeFile } from 'xlsx-js-style';
>
const ExportExcel = () => {
  const handleExport = useCallback(() => {
    const ws = utils.aoa_to_sheet([...header,...body]);
    >
    const borderStyle = {
      top: { style: 'thin', color: { rgb: '000000' } },
      bottom: { style: 'thin', color: { rgb: '000000' } },
      left: { style: 'thin', color: { rgb: '000000' } },
      right: { style: 'thin', color: { rgb: '000000' } },
    };
    >
     // 헤더 스타일
       header.forEach((_, colIdx) => {
      const addr = utils.encode_cell({ r: 0, c: colIdx });
      if (ws[addr]) {
        ws[addr].s = {
          fill: { fgColor: { rgb: 'D9D9D9' } },
          font: { bold: true },
          border: borderStyle,
          alignment: { horizontal: 'center', vertical: 'center' },
        };
      }
    });
>
   // body 스타일
    for (let r = 1; r < wsData.length; r++) {
      for (let c = 0; c < header.length; c++) {
        const addr = utils.encode_cell({ r, c });
        if (ws[addr]) {
          ws[addr].s = {
            border: borderStyle,
            alignment: { vertical: 'center', horizontal: 'left' },
          };
        }
      }
    }
>
  // 열 너비
    const colWidths = [100, 80, 300, 80, 100, 80, 120, 150];
    ws['!cols'] = header.map((_, idx) => ({
      wpx: colWidths[idx] ?? 80,
    }));
      >
    const wb: WorkBook = utils.book_new();
    utils.book_append_sheet(wb, ws, '원하는 시트명');
    writeFile(wb, '파일명.xlsx');
  }, []);
      >
    return (
     <div className="w-120pxr">
       <Button onClick={handleExport}>Export</Button>
     </div>
  );
};
>
export default ExportExcel;

⚠️ 주의 사항

여기서 스타일 적용을 위해 가~장 중요한건 위의 xlsx 라이브러리 사용할때와 차이점이 있다.

그 전에는 스타일을 신경쓰지 않아서 공식문서(https://docs.sheetjs.com/docs/#export-an-html-table-to-excel-xlsx)에 나온대로 writeFileXLSX를 사용했다

그런데 xlsx-js-style를 사용해도 스타일이 적용 안되고, 간단한 예제를 적용해봐도 안돼서 엄청 삽질했다..

그러던중 공식문서(https://github.com/gitbrent/xlsx-js-style/?tab=readme-ov-file#cell-style-example) 예제를 따라하는데 writeFile 를 사용하는거였다..

이렇게 간단히 해결되는 문제였다니.. 문서를 좀 더 꼼꼼히 봐야할 필요가 있다..

노드 버전을 20 이상으로 바꾸면 해결되긴 한다.

근데 당장 바꿀 수 없어 다른 방식으로 해결해야 했다.

문제 코드

import { z } from 'zod';
>
const FileWithType = z.object({
  file: z.instanceof(File),
  type: z.enum(['PC', 'MOBILE']),
});

zod로 타입 검증을 하는 도중, 브라우저 전용 객체인 File이 서버 환경(node v18)에서는 정의되지 않아 빌드 시 발생한 오류

해결한 코드

import { z } from 'zod';
>
const FileWithType = z.object({
  file: typeof File !== 'undefined' ? z.instanceof(File) : z.any(),
  type: z.enum(['PC', 'MOBILE']),
});

=> 브라우저 환경에서만 File 검증

"인증번호 받기" 버튼 클릭 후 "재전송", "확인" 버튼이 있는 input(InputWithButton 컴포넌트)의 width가 깨지는 현상이 발생

해결방법

기존 코드

 <div className="flex w-full gap-10pxr">
        <div className="w-[calc(100% - 7.125rem)]">
          <Input/>
        </div>
        <div className="w-114pxr">
          <SquareButton>
            {buttonText}
          </SquareButton>
        </div>
      </div>

safari에서 calc가 안되는 것 같아 수정이 필요했다.

수정한 코드

 <div className="flex w-full gap-10pxr">
        <div className="min-w-0 flex-1">
          <Input/>
        </div>
        <div className="w-114pxr flex-shrink-0">
          <SquareButton>
            {buttonText}
          </SquareButton>
        </div>
      </div>

"flex-1"로 채워주니 UI가 깨지지 않고 잘 나왔다!

리스트 페이지에 두 가지 탭이 있는데 탭은 헤더 아래에 sticky로 붙이고, 스크롤 시 h1 태그 사라지고 모바일 헤더에 centerTitle 들어가게 하기

      <MoHeader
          centerTitle={isFixed ? '헤더 타이틀' : undefined}
        />

문제 상황

safari에서 스크롤 했을 때 헤더 타이틀이 깜빡거리는 문제가 발생

❌ 문제 코드

  const tabRef = useRef<HTMLDivElement>(null);
>
  useEffect(() => {
    const handleScroll = () => {
      if (tabRef.current) {
        const { top } = tabRef.current.getBoundingClientRect();
        setIsFixed(top === 56);
      }
    };
>
    window.addEventListener('scroll', handleScroll);
    return () => {
      window.removeEventListener('scroll', handleScroll);
    };
  }, [setIsFixed, tabRef]);

원인은 사파리 브라우저에서 스크롤 시 바운스 현상이 나타나서 .getBoundingClientRect() 메서드로 잡은 위치가 계속 변해서 발생한 문제였다

sticky로 고정한 탭의 위치를 알면 .getBoundingClientRect() 메서드를 사용하지 않아도 되는데 더 간단한 방법을 떠올리지 못해서 계속 삽질만하다가 몇시간을 보냈다..

🆗 수정한 코드

  useEffect(() => {
    const handleScroll = () => {
      const top = window.scrollY;
      setIsFixed(top >= 73);
    };
    >
    window.addEventListener('scroll', handleScroll);
    return () => {
      window.removeEventListener('scroll', handleScroll);
    };
  }, [setIsFixed]);

useRef 사용하지 않고 window.scrollY로 위치를 찾아 고정해주니 바운스 현상에 영향을 받지 않고 타이틀도 깜빡이지 않았다.

프로젝트의 개발 환경

• Next.js v14
• Typescript v5
• react v18
• ES 모듈

TinyMCE를 적용하는 방법은

1. 클라우드 호스팅 (월 1000회 로드 무료, 이후 유료)
2. 패키지 매니저로 설치하는 셀프 호스팅 (무료)
3. zip 파일에서 추출하는 셀프 호스팅 (무료)

이렇게 세 가지 방법이 있고, 나는 패키지 매니저를 사용했다.

공식 문서 - 패키지 매니저를 통한 셀프 호스팅

TinyMCE의 경우 에디터 사용하는 것 보단 나중에 환경 셋팅하는 데 더 시간이 많이 들었다. 참고할 공식 문서의 자료가 여기저기 있는 느낌?이라 React 기반 기술문서를 제대로 활용하지 못했다. 그러다 보니 js 기반으로 된 내용을 typescript에 맞게 환경을 수정하는 과정이 필요했다.

1. tinymce, @tinymce/tinymce-react, fs-extra 패키지 설치

yarn add tinymce @tinymce/tinymce-react fs-extra

2. {프로젝트}/postinstall.mjs 생성

TinyMCE 디렉토리를 생성하기 위해 프로젝트 root 경로에 postinstall 스크립트 설정

import fse from 'fs-extra';
import path from 'path';
import { fileURLToPath } from 'url';
import { dirname } from 'path';
>
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename); 
>
fse.emptyDirSync(path.join(__dirname, 'public', 'tinymce'));
fse.copySync(
  path.join(__dirname, 'node_modules', 'tinymce'),
  path.join(__dirname, 'public', 'tinymce'),
  { overwrite: true }
);
>
console.log('✅ TinyMCE files copied successfully!');

ES 모듈을 사용한다면 이 코드를 참고하는 걸 추천한다. 공식문서의 예시를 따랐는데, CI/CD 환경에서 import.meta.dirname을 사용하는 빌드 스크립트가 실패하는 현상이 발생했다. Node.js에서 ES Module(ESM)을 사용할 때는 현재 디렉토리 경로를 얻기 위해 import.meta.url을 사용해야 한다.

3. package.json에 postinstall 스크립트와 .gitignore에 /public/tinymce 디렉토리를 추가한다.

yarn install 실행 시 자동으로 postinstall 실행된다.

// package.json
>
{
  "scripts": {
    "postinstall": "node ./postinstall.mjs"
  }
}

// .gitignore
>
/public/tinymce/

4. 터미널에서 yarn postinstall 실행

5. 에디터 컴포넌트 생성 및 적용

공식 문서 - React 기반 통합 기술 문서 를 참고하면 에디터 컴포넌트 props를 사용하기 수월할 것이다.

[내가 수정 및 커스텀 한 목록]

1. 라이선스키 GPL 사용 (대소문자 구분 ❌) 공식문서에 관련 자료가 있으니 본인 상황에 맞게 사용하면 된다. 공식 문서 - 라이선스키

2. initialValue 대신 value, onEditorChange 사용 에디터에 내용을 작성하거나 엔터 입력했을 때 커서가 제대로 동작하지 않아서 controlled-component 방식을 사용했다. 하지만 TinyMCE는 uncontrolled-component 기반으로 설계되었기 때문에 나중에 리팩토링 해도 좋을 것 같다. 공식 문서 - uncontrolled-component

3. init props에 사용할 menubar 추가 다양한 기능을 사용하고자 menubar: false 대신 원하는 메뉴바 탭 이름을 작성했다. 메뉴바 탭 이름 클릭시 드롭다운으로 나오는 메뉴들 또한 커스텀이 가능하다. 메뉴와 툴바에서 중복될 필요 없는 부분도 제거했다.

4. 다중 이미지 업로드 핸들러 기본 이미지 업로드 기능은 한 개의 이미지 파일만 업로드 가능한데 여러 이미지를 업로드 하기 위해 handleMultipleImages 함수를 구현했다.

   그냥 이미지를 첨부하면 base64로 인코딩 돼 엄~청 긴 문자열로 반환된다. 이 문자열을 서버에 저장하면 DB 용량을 많이 차지할 뿐만 아니라, 페이지 로딩 시 불필요하게 긴 문자열을 파싱해야 해서 성능에도 좋지 않다.

   이 함수는 파일 정보가 담긴 formData를 서버에 보내면, 서버에서 AWS S3에 이미지를 저장하고 생성된 URL을 반환해 준다. 이 반환된 url로 이미지 태그를 생성해서 에디터에 추가한다.

init props에 setup 키워드를 사용해 다중 이미지 업로드, 드래그 앤 드랍 이미지 업로드 기능을 커스텀해줬다.

공식 문서 예시를 참고해 커스텀 한 코드이다.

import { useRef } from 'react';
>
declare global {
  interface Window {
    tinymce: any;
  }
}
import { Editor } from '@tinymce/tinymce-react';
import { Editor as TinyMCEEditor } from 'tinymce';
import ProductAPI from '@/apis/product';
>
interface Props {
  value: string;
  onChange: (value: string) => void;
}
>
export default function WebEditor({ value, onChange }: Props) {
  const editorRef = useRef<TinyMCEEditor | null>(null);
  >
    // 다중 이미지 업로드 핸들러
  const handleMultipleImages = async (files: FileList) => {
    try {
      const formData = new FormData();
      >
      Array.from(files).forEach((file, index) => {
        formData.append(`descriptionImages[${index}]`, file); // req 객체에맞게 formData 작성
      });
>
   // 서버에 이미지 전송하고, 반환된 S3 URL 배열을 통해 이미지 태그 생성
      const { data, status } = await /*API 요청 경로*/; 
>
      if (status === 200 && editorRef.current) {
        const imageHtml = data
          .map((url: string) => `<img src="${url}" alt="uploaded image" />`)
          .join('<br />');
>
        editorRef.current.insertContent(imageHtml);
      }
    } catch (error) {
      console.error('Image upload failed:', error);
    }
  };
>
  return (
    <>
      <Editor
        tinymceScriptSrc="/tinymce/tinymce.min.js"
        licenseKey="gpl"
        onInit={(_evt, editor) => (editorRef.current = editor)}
        value={value ?? ''}
        onEditorChange={(content) => onChange(content)}
        init={{
          height: 500,
          menubar: 'file edit view insert format tools help', // except: table
          menu: {
            file: {
              title: 'File',
              items: 'newdocument restoredraft | preview',
            },
            edit: {
              title: 'Edit',
              items: 'undo redo | cut copy paste | selectall | searchreplace',
            },
            view: {
              title: 'View',
              items:
                'code | visualaid visualchars visualblocks | spellchecker | preview fullscreen',
            },
            insert: {
              title: 'Insert',
              items:
                'image link addcomment pageembed codesample inserttable | math | charmap emoticons hr | pagebreak nonbreaking anchor | insertdatetime',
            },
            format: {
              title: 'Format',
              items:
                'bold italic underline strikethrough superscript subscript codeformat | styles blocks fontfamily fontsize align lineheight | forecolor backcolor | language | removeformat',
            },
            tools: {
              title: 'Tools',
              items:
                'spellchecker spellcheckerlanguage | a11ycheck code wordcount',
            },
            help: { title: 'Help', items: 'help' },
          },
          plugins: [
            'advlist',
            'autolink',
            'lists',
            'link',
            'image',
            'charmap',
            'anchor',
            'searchreplace',
            'visualblocks',
            'code',
            'fullscreen',
            'insertdatetime',
            'preview',
            'help',
            'wordcount',
          ],
          toolbar:
            'undo redo | blocks | ' +
            'bold italic forecolor removeformat | alignleft aligncenter ' +
            'alignright alignjustify | bullist numlist outdent indent | ' +
            'multipleimages  |  | preview |help',
          content_style:
            'body { font-family:Helvetica,Arial,sans-serif; font-size:14px }',
          setup: (editor) => {
            // `image` 아이콘과 `multipleimages` 이름으로 다중 이미지 업로드 기능 커스텀
            editor.ui.registry.addButton('multipleimages', {
              icon: 'image',
              onAction: () => {
                const input = document.createElement('input');
                input.setAttribute('type', 'file');
                input.setAttribute('multiple', 'true');
                input.setAttribute('accept', 'image/*');
>
                input.onchange = async (e) => {
                  const files = (e.target as HTMLInputElement).files;
                  if (files && files.length > 0) {
                    await handleMultipleImages(files);
                  }
                };
>
                input.click();
              },
            });
            // 드래그 앤 드랍 다중 이미지 업로드
            editor.on('drop', async (e) => {
              const dataTransfer = e.dataTransfer;
              if (dataTransfer && dataTransfer.files.length > 0) {
                e.preventDefault();
>
                // 이미지 파일만 필터링
                const imageFiles = Array.from(dataTransfer.files).filter(
                  (file) => file.type.startsWith('image/')
                );
>
                if (imageFiles.length > 0) {
                  await handleMultipleImages(
                    Object.assign(imageFiles, {
                      item: (i: number) => imageFiles[i],
                    })
                  );
                }
              }
            });
          },
        }}
      />
    </>
  );
}

이렇게 하면 에디터가 생성이 된다!

React-Quill - 공식 문서

어떤 에디터를 사용할 지 찾아본 후 나름대로 React-Quill로 첫 선택을 했다.

그 이유는

장점

• react와 호환성이 좋다.
• 이미지 사이즈 조절 가능
• 무료 라이브러리

단점

• 이미지 핸들러가 없다.

그 외에도 자유도가 높아 커스텀이 용이하다는 장점이 있는 것 같다. 하지만 나는 신입 개발자이고 웹 에디터를 사용해본 경험이 없기 때문에 어떤걸 커스텀 해야하는지 모르는 상태였지만 참고 자료가 많은 것 같다는 이유로 용감하게도 첫 선택을 하게 되었다.

사용하지 않은 이유

라이브러리를 설치하고 호기롭게 시작했는데, 얼마 안가서

개발자 도구에 이런 오류가 뜨면서 잘 동작하지 않았다. 찾아보니 지원되지 않는 DOM 이벤트인 'DOMNodeInserted'를 사용하고 있기 때문에 발생하는 오류인 것 같았다. 다들 어떻게 적용하고 잘 쓰는지.. 대단하다

어떻게 해결해야할 지 잘 파악이 되지 않아서 그 다음 대안이었던 Toast-ui/editor로 빠르게 갈아탔다.

Toast-ui/editor - 공식 문서

사실 react-quill 보단 이 에디터를 더 사용하고 싶었다. UI가 귀엽고 자료 조사 할 때 장점이 많아 보였다. 그리고 v3가 출시되고 사용법이 직관적이면서 많이 개선된 것 같아 자신감이 뿜뿜했다.

장점

• 한국어 가이드 제공 및 한글 지원
• 다크모드 지원 (안쓸거같긴했음)
• Markdown, wysiwyg 둘 다 지원
• 무료 라이브러리

단점

• 이미지 사이즈 조절 불가능
• SSR 미지원 (React v18도 지원 안한다고 하는데 확실하지 않음)

이미지 사이즈 조절이 불가능하고, Next.js 사용중인데 SSR 미지원 한다고하니 우선 순위에서 내려갔었다. 근데 이미지 사이즈 조절 기능이 필수는 아니었고, 에디터는 CSR 환경에서만 사용하면 될 것 같아서 React-Quill의 대안으로 선택했다.

사용하지 않은 이유

상품 상세 페이지를 작성하기 위한 에디터라서 정렬과 폰트 사이즈 조절 기능이 필요했는데 마크다운 기반의 에디터라 이를 제공하지 않았다. 마크다운 에디터로 제한하고, inline style을 적용하게끔 직접 구현하려고 시도했는데, 미리보기 뷰어에서는 style 적용이 안돼서 또 다른 대안을 찾아 나서게 되었다...

근데 간단한 기능이 필요한 사람일 경우 적용하는 게 어렵지 않아서 추천 한다.

TinyMCE - 공식 문서

가장 많이 알려진 두 에디터를 실패하고 유료 에디터까지 고려하던 중에 선택하게 되었는데 최종으로 이 에디터를 사용하게 되었다.

장점

• 기본 제공되는 기능이 엄청 다양하다.
• Toast-ui/editor 만큼 사용법이 간단하다.
• 클라우드 호스팅을 제공해서 언제나 최신 기술 사용이 가능하다.

단점

• 클라우드 호스팅의 경우 에디터 로드 횟수에 따라 과금된다. - 요금 정책

과금에 대해 먼저 알고있었어서 에디터 사용하는 데 초반 고려대상이 아니었다. 하지만 이제서야 실제 유저가 사용해야 할 기능에 대해 파악하게 되어서 공식문서에 있는 수많은 기능을 보고 선택하지 않을 수 없었다.

아래는 사용 방법 및 커스텀 한 내용을 정리한 포스팅이다.

[Next.js 14, Typescript] TinyMCE 웹 에디터 라이브러리 사용법 (+ 다중 이미지 업로드)

정렬, 폰트 사이즈 외에도 어지간한 기능은 다 제공하고 있었다. (물론 다 무료는 아님)

제공하는 무료 기능이 충분해서 선택하게 되었다. 그리고 이미 선택 한 후에 찾아봤지만 npm trends 가 제일 높다;;

install

패키지 매니저는 yarn을 사용하고 있다

yarn add @toast-ui/react-editor

node_modules에

추가됐는지 확인

사용하기

WebEditor.tsx

import { Editor } from '@toast-ui/react-editor';
import '@toast-ui/editor/dist/toastui-editor.css';
>
const WebEditor = () => {
  return (
    <Editor
      previewStyle="tab"
      height="300px"
      initialEditType="wysiwyg"
      initialValue="hello"
      useCommandShortcut={true}
      hideModeSwitch={true}
      toolbarItems={[
        ['heading', 'bold', 'italic', 'strike'],
        ['hr', 'quote'],
        ['ul', 'ol'],
        ['table', 'image', 'link'],
        ['scrollSync'],
      ]}
    />
  );
};
>
export default WebEditor;

작성하고 원하는 페이지에 import해보면 아래처럼 적용이 된다.

근데 아래와 같이 500에러가 나서 찾아보니

Toast UI Editor는 클라이언트 사이드에서만 실행되어야 하는 컴포넌트이기 때문에 dynamic import를 사용하여 클라이언트 사이드에서만 컴포넌트를 렌더링하도록 수정했다. Next.js 공식문서 - With no SSR 참고

컴포넌트 import 한 페이지에 아래의 코드를 작성했더니 해결됐다.

'use client';
>
import dynamic from 'next/dynamic';
>
const WebEditor = dynamic(() => import('에디터 컴포넌트 위치'), {
  ssr: false,
});

패키지 매니저는 yarn을 사용했는데 공식문서에서 default로 제공하는 내용과 좀 차이가 있어 npm을 사용하는게 더 나을 것 같다.

Husky 공식문서 - Get Started

Get Started

1. 설치

yarn add --dev husky

2. init

(yarn은 init 대신 How to 섹션에 있는 내용을 참고해야 함)

1) package.son script 작성

{
  "scripts": {
    // Yarn doesn't support prepare script
    "postinstall": "husky",
    // Include this if publishing to npmjs.com
    "prepack": "pinst --disable",
    "postpack": "pinst --enable"
  }
}

2) Run

# Yarn doesn't support `prepare`
yarn run postinstall

3. commitlint 라이브러리 추가

커밋 컨벤션 체크를 위해 사용 commitlint 공식문서 Get Started

1) 설치

yarn add --dev @commitlint/{cli,config-conventional}

타입스크립트 사용으로 @commitlint/types도 추가해줬다

yarn add --dev @commitlint/types

2) commitlint.config.ts 파일 추가

echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.ts

3) typescript-configuration 설정 configuration-rules 참고해서 작성하면 된다. 나는 팀원분이 설정하신 파일을 그대로 사용했다 키득키득

import type { UserConfig } from '@commitlint/types';
import { RuleConfigSeverity } from '@commitlint/types';
>
// 상세 규칙 : https://commitlint.js.org/reference/rules.html
const Configuration: UserConfig = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      RuleConfigSeverity.Error,
      'always',
      [
        'FEAT',
        'FIX',
         ...
      ],
    ],
    'type-case': [RuleConfigSeverity.Error, 'always', 'upper-case'], // type-enum 대문자만 허용
    'subject-max-length': [RuleConfigSeverity.Warning, 'always', 50], // 제목 50자 이내
    'subject-full-stop': [RuleConfigSeverity.Error, 'never', '.'], // 제목 끝에 마침표 사용하지 않음
  },
};
>
export default Configuration;

4. ./husky/commit-msg 파일 생성

.husky/- 폴더 하위의 파일명으로 파일 컨벤션(ex. commit-msg, pre-push 등) 작성되어 있음 참고!

yarn commitlint --edit "$1" || {
  echo "사용하고 싶은 commit 에러 메시지 작성"
  exit 1
}

5. lint-staged 라이브러리 추가

1) 설치

yarn add lint-staged --dev

2) script 추가

"lint-staged": {
    "src/**/*.{js,jsx,ts,tsx}": [
      "eslint --cache"
    ]
  },

3) ./husky/pre-push 파일 추가

yarn lint-staged

검색 해도 다른 스크롤 이슈가 나오고 이 문제에 대한 글을 못찾겠어서 클로드에 물어보니 바로 몇가지 해결방법을 알려줬다..

그 중 간단하게 해결 가능한 방법은

<Select
     MenuProps={{
    disableScrollLock: true,
  }}
>

이렇게 MenuProps로 MUI의 disableScrollLock 프로퍼티 사용하는 방법으로 해결했다.

const theme = createTheme({
  components: {
    MuiTextField: {
      styleOverrides: {
        root: {
          '& .MuiOutlinedInput-root': commonInputStyles,
          '& .MuiOutlinedInput-root.Mui-disabled': {
            '& fieldset': {
              borderColor: '#F2F4F6',
            },
            '& input': {
              borderRadius: '6px',
              backgroundColor: '#F2F4F6',
              WebkitTextFillColor: '#404048', // 이 색상을 바꿔주면 됨
            },
          },
        },
      },
    },
  },
});

sx={{ minWidth: 'unset'} 을 사용하여 버튼의 기본 최소 너비를 제거했더니 해결됐다.

결과물

코드

   <Button
     variant="outlined"
     sx={{
       minWidth: 'unset',
       width: '40px',
       height: '40px',
       padding: 0,
       borderColor: '#4E5968',
       '&:hover': {
         borderColor: '#4E5968',
         backgroundColor: 'white',
        },
      }}
    >
      <RemoveIcon
        sx={{ fontSize: '16px', color: '#4E5968' }}
      />
   </Button>
>
   <Button
     variant="outlined"
     sx={{
       minWidth: 'unset',
       width: '40px',
       height: '40px',
       padding: 0,
       borderColor: '#4E5968',
       '&:hover': {
         borderColor: '#4E5968',
         backgroundColor: 'white',
        },
      }}
     >
       <AddIcon sx={{ fontSize: '16px', color: '#4E5968' }} />
     </Button>

• MUI에서 반응형 레이아웃을 제공하는 컴포넌트로 유연성이 높다.
• 레이아웃에는 container와 item 두 가지 유형이 있다.
• <Grid container>가 최대 12까지 너비라고 생각하고 <Grid item>의 너비를 정해주면 된다
• breakpoint은 xs, sm, md, lg, xl 5가지가 있다.

• *breakpoints (MUI 공식문서)**

  `xs` : extra-small (스크린(브라우저) 너비가 0~600px일 때 사용)
  `sm` : small (600 ~ 900px)
  `md` : medium (900 ~ 1200px)
  `lg` : large (1200 ~ 1536px)
  `xl` : extra-large (1536px ~ )

이렇게 breakpoint를 지정하면 브라우저 크기 조정할 때 각 너비에 따라 컴포넌트의 크기가 변한다. createThem을 이용해 breakpoint 별로 커스텀도 가능하다.

<Grid container>

옵션

• direction : row, column 으로 지정할 수 있는 옵션 (참고로, direction=colum인 경우 breakpoint는 지원되지 않는다고 한다.)

내용 계속 추가 예정

<Grid> 공식문서

ex)

...
        setRows(
'이 data =>' data.resData.content.map((item: FaqRes) => ({
            ...item,
            isFrequency: item.isFrequency ? '적용' : '미적용',
            createdAt: formatToKSTDateTime(item.createdAt as string),
            creator: `${item.creatorName}/${item.creatorEmail}`,
          }))
        );
...

2. spread 문법을 사용하면서 똑같은 배열을 왜 만들어서 활용하는지 궁금함이 생겼다

React에서는 상태를 직접 변경하는 것이 아니라, 상태의 복사본을 만들어 수정한 후 그 복사본으로 상태를 업데이트하는 것이 중요한 원칙이라고 한다.

왜 불변성을 유지해야 하나요?

성능 최적화: React는 상태가 변경될 때마다 컴포넌트가 다시 렌더링됩니다. 상태가 직접 변경되면 React는 변경된 부분을 감지하지 못할 수 있습니다. 하지만 불변성을 유지하면 React는 상태 변경을 정확하게 감지할 수 있습니다.

예측 가능성: 상태를 직접 변경하면 예상치 못한 부작용이 발생할 수 있습니다. 불변성을 유지하면 상태 변경이 명확하게 관리되므로 코드의 예측 가능성이 높아집니다.

디버깅 용이: 불변성을 유지하면 상태 변경 전후를 비교하기 쉬워지고, 상태 추적이나 디버깅이 더 쉬워집니다.

그럼 모든 경우에 복사본을 생성해서 불변성을 유지해야 할까?

그건 아니다.

대표적으로

1. 로컬 변수: 함수 내부에서 사용되는 로컬 변수나 객체는 불변성을 유지할 필요가 없습니다. 이들은 함수가 실행될 때 생성되고, 함수가 끝나면 메모리에서 해제되기 때문에 불변성을 강제할 필요가 없습니다.
2. 성능이 중요한 경우: 큰 배열이나 객체를 반복적으로 처리해야 하는 상황에서는 불변성을 유지하려면 성능에 부담이 될 수 있습니다. 이럴 때는 불변성을 유지하지 않고, 직접적으로 변경하여 성능을 최적화할 수 있습니다. 하지만 이는 상황에 따라 신중하게 판단해야 합니다.

이러한 경우에는 불변성을 유지하지 않아도 된다.

요약: 불변성을 유지하는 기준

• 상태 관리: React 상태나 Redux 상태와 같이 변경이 감지되어야 하는 경우, 불변성을 유지해야 합니다.
• 로컬 작업: 함수 내부의 로컬 작업이나 불변성을 유지할 필요가 없는 곳에서는 불변성을 강제하지 않아도 됩니다.
• 성능 고려: 성능이 중요한 경우 불변성을 포기할 수 있지만, 그에 따른 부작용을 충분히 고려해야 합니다.

기본적으로 layout.tsx 에서 전역으로 font 설정을 적용하고 있어서

const notoSansKr = Noto_Sans_KR({
  subsets: ['latin-ext'],
  style: ['normal'],
  weight: ['400', '500', '600', '700'],
  display: 'swap',
  fallback: ['system-ui', 'arial'],
});
>
...
>
  <body className={notoSansKr.className}>
    ...
  </body>

처음에는 MUI의 createTheme과 ThemeProvider를 layout.tsx 파일에 적용해줬다. 하지만 MUI는 CSR 환경에서 사용되기 때문에 오류가 발생해서 따로 Provider 파일을 생성해 넣어줬다.

해결 방법

우선 NotoSansKR의 ttf를 다운받아 /public 폴더에 넣어줬다. (Google Font 다운로드)

그 후, global.scss 파일에 font-face를 설정해줌 (layout.tsx에서 사용 중)

global.scss (사용할 굵기만 넣어줘도 됨)

@font-face {
  font-family: 'Noto Sans KR';
  src: url(../../public/fonts/NotoSansKR-Regular.ttf);
  font-weight: 400;
}
>
@font-face {
  font-family: 'Noto Sans KR';
  src: url(../../public/fonts/NotoSansKR-Medium.ttf);
  font-weight: 500;
}
>
@font-face {
  font-family: 'Noto Sans KR';
  src: url(../../public/fonts/NotoSansKR-SemiBold.ttf);
  font-weight: 600;
}
>
@font-face {
  font-family: 'Noto Sans KR';
  src: url(../../public/fonts/NotoSansKR-Bold.ttf);
  font-weight: 700;
}

ThemeRegistry.tsx

'use client';
>
import { createTheme, ThemeProvider } from '@mui/material/styles';
import CssBaseline from '@mui/material/CssBaseline';
>
const theme = createTheme({
  typography: {
    fontFamily: ['Noto Sans KR', 'Arial', 'sans-serif'].join(', '),
  },
>
});
>
export default function ThemeRegistry({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <ThemeProvider theme={theme}>
      <CssBaseline />
      {children}
    </ThemeProvider>
  );
}

이렇게 설정해준 후 layout.tsx 파일에서 태그로 적용하고 싶은 범위를 지정해주면 된다!

  import '@/styles/global.scss';
>
  ...
  >
      <body>
        <ThemeRegistry> // <---- 요기부터
          <Header />
          <SideBar />
          <main>{children}</main>
        </ThemeRegistry> // <---- 요기까지
      </body>

app/layout.tsx

import type { Metadata } from 'next';
import { Noto_Sans_KR } from 'next/font/google';
import '@/src/styles/global.scss';
>
const notoSansKr = Noto_Sans_KR({
  subsets: ['latin-ext'], // 확장된 라틴 문자를 포함해 한글과 영문 모두 지원 가능
  style: ['normal'], 
  weight: ['400', '500', '600', '700'], // 각 굵기에 따른 스타일 적용 가능
  display: 'swap', // 폰트가 로드되는 동안 시스템 폰트 사용하다, 로드가 완료되면 지정된 폰트로 교체
  fallback: ['system-ui', 'arial'], // 지정한 폰트 사용 불가 시 대체 폰트를 순서대로 나열
});
>
export const metadata: Metadata = {
  title: 'title',
  description: 'description',
};
>
export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="ko">
      <body className={notoSansKr.className}> // body의 className에 변수명 써서 font 설정
        <main>{children}</main>
      </body>
    </html>
  );
}

import styles from './index.module.scss';
import { UserInfoProps } from '@/src/types/interface';
>
interface Props {
  userInfo: UserInfoProps;
  onInputChange: (field: string, value: string | boolean) => void;
}
>
const MarketingInfo = ({ userInfo, onInputChange }: Props) => {
  return (
    <div className={styles.marketingWrapper}>
      <div className={styles.marketingTitle}>
        <p>마케팅 정보 수신 동의</p>
        <span>이벤트, 특가, 혜택 등 유용한 정보를 알려드립니다.</span>
      </div>
      <div className={styles.marketingRadio}>
        <label className={styles.radioLabel}>
          <input
            type="radio"
            name="marketing"
            checked={userInfo.isAgreeMarketing}
            onChange={() => onInputChange('isAgreeMarketing', true)}
          />
          <span className={styles.customRadio}></span>
          수신
        </label>
        <label className={styles.radioLabel}>
          <input
            type="radio"
            name="marketing"
            checked={!userInfo.isAgreeMarketing}
            onChange={() => onInputChange('isAgreeMarketing', false)}
          />
          <span className={styles.customRadio}></span>
          비수신
        </label>
      </div>
    </div>
  );
};
>
export default MarketingInfo;

.marketingWrapper {
  display: flex;
  flex-direction: column;
  margin-bottom: 30px;
}
>
.marketingTitle {
  display: flex;
  flex-direction: column;
>
  p,
  span {
    color: #4e5968;
  }
>
  p {
    margin: 8px 0;
  }
  span {
    font-size: 12px;
    margin-bottom: 15px;
  }
}
>
.marketingRadio {
  display: flex;
  gap: 40px;
}
>
.radioLabel {
  display: flex;
  align-items: flex-start;
  font-size: 12px;
  color: #404048;
  cursor: pointer;
>
  input {
    display: none;
  }
>
  .customRadio {
    width: 18px;
    height: 18px;
    border: 2px solid #e5e7ea;
    border-radius: 50%;
    margin-right: 8px;
    display: inline-block;
    position: relative;
>
    &::after {
      content: '\2714'; // 유니코드에서 체크 표시
      font-size: 9px;
      color: white;
      position: absolute;
      top: 50%;
      left: 50%;
      transform: translate(-50%, -50%) scale(0);
      transition: transform 0.2s ease;
    }
  }
>
  input:checked + .customRadio {
    background-color: #002fb4;
    border-color: #002fb4;
>
    &::after {
      transform: translate(-50%, -50%) scale(1);
    }
  }
}

$ git remote add origin https://계정@bitbucket.org/이하 주소(HTTPS URL)

저장소 연결 후 git push 받았는데 아래와같은 오류가 났다.

local 저장소와 bitbucket 저장소가 관련 기록이 없어서 생기는 오류라고 한다..

$ git pull origin main --allow-unrelated-histories

입력했더니 해결됐다!

참고 자료

• git push, pull (fatal: refusing to merge unrelated histories) 에러
• https://despiteallthat.tistory.com/84

우리 팀은 상태관리 툴로 Zustand를 사용했다. 첫 리액트 프로젝트이다 보니 상태관리 툴을 왜 써야하는지가 와닿지 않아서 Redux 사용을 미루고 있었다. 근데 로그인 상태를 유지 시키기 위해서는 전역적으로 상태를 관리할 필요가 있다고 판단해 상태관리 툴의 도입을 고려하는데, 중간에 사용하려니까 Redux 설계를 할 생각에 좀 막막했다..

그러던 중 친구의 추천으로 zustand를 알게 되었는데, 사용법이 매우 간단하고 Redux와 같은 Flux 패턴을 사용하고 있어 개념을 따로 익히지 않아도 된다는 점이 팀원들에게도 부담이 덜 되겠다고 생각했다.

Zustand 사용법

설치

npm install zustand

사용법

일단 zustand는 create 함수를 통해 store를 생성 할 수 있다. 초기 설정이 이게 끝이다 so 간편 Provider로 감쌀 필요도 없다. 약간 커스텀 Hook을 만들어서 사용하는 느낌?! 그래서 일반적으로 store이름 앞에 use를 붙인다고 한다.

Typescript로 store 생성 후 바인딩 하여 사용하는 예제

// store 생성
import { create } from 'zustand'
>
type Store = {
  count: number
  inc: () => void
}
>
const useStore = create<Store>()((set) => ({
  count: 1,
  inc: () => set((state) => ({ count: state.count + 1 })),
}))
>
// 전역 state 및 action 함수 사용
function Counter() {
  const { count, inc } = useStore()
  return (
    <div>
      <span>{count}</span>
      <button onClick={inc}>one up</button>
    </div>
  )
}

문제 상황

1

로그인을 하는데 새로 고침을 하니까 state가 초기화 되어 버렸다..

2

이전 글을 보면 react-router-dom의 loader를 통해 두 개의 페이지(개인학습, 퀴즈)에서 사용할 일상생활 수어 openAPI 데이터를 한 번에 받아오게끔 구현했었다. 근데 loader는 데이터를 다 불러와야지만 화면 전환이 돼서, 사용자 입장에서 멈춘 화면을 보게 되는데 실제 웹 사이트를 사용할 때 이러면 사용자들이 다 떠나가게 된다..

그래서 React <Suspense>를 사용해 자식(개인학습, 퀴즈 페이지)이 로딩을 완료할 때까지 폴백을 표시하려고 했다.

근데.. Suspense로 두 페이지를 감싸도 제대로 동작하지 않았다 왜일까.. 거의 하루 중 반을 잡고있었는데도 해결이 안돼서 zustand를 이용한 방법으로 해결했다.

해결 방법

1

새로 고침 시 초기화 되는 문제를 해결하기 위해 찾아보니 persist라는 메서드가 있어서 이를 활용해 상태를 유지시켜 줬다.

공식 문서의 Persisting store data

2

1. zustand의 fetchData라는 action 함수로 axios 요청 보낸 후 data(배열)라는 state에 return값을 저장하고, loading 이라는 state를 true로 변경했다.

2. 값을 넘겨 받을 페이지에서 data, loading state와 fetchData 함수를 호출해, useEffect에 data의 길이가 0이면 fetchData 함수를 실행하도록 작성했다. 그리고 loading state를 이용해 삼항 연산자로 로딩 화면과 로딩 후 보여줄 페이지를 return 부분에 작성해줬다.

참고 자료 zustand 공식 문서