📗 Docs 페이지 구현하기

지난번에 코딩해듀오에 대한 UT를 진행했다.
사용자들이 미션 생성 이라던지, 페어룸의 기능들이 왜 있는건지, 어떤 순서로 진행해야하는지 등에 대한 정보가 tooltip 이나 설명 몇줄로는 설명되지 않은 듯 했다.
그래서 코딩해듀오만의 용어와 사용법들에 대한 정보를 담고 있는 Docs 페이지를 만들기로 했다.

⭐️ mdn 이 우리가 원하는 디자인과 유사해서 많이 참고했다!

💭 고민 -(1) 어드민 페이지 vs 하드코딩

어드민 페이지를 만들어서 편집,수정,삭제가 가능하게 할 지 하드코딩으로 직접 넣어줄지 고민했다.

어드민 페이지의 장단점

어드민 페이지가 있다면 내용을 수정해야 할 때 배포와 코드 수정 없이 간편하게 업로드 사용할 수 있다.
만약 어드민 페이지가 있다면 자유로운 스타일 변경을 위해 마크다운 형식을 제공해주어야 할 것이고, 각 섹션마다 id 를 넣어주어야 한다. 그리고 새로운 서버 api 가 필요하다.
하지만 코딩해듀오 가이드는 한번 제대로 작성이 되면 이후에 변경될 일이 없어서 이 문서 때문에 백엔드에서 추가 api를 생성하고, 프론트에서도 의존성을 추가해 주는게 오버 엔지니어링 이라고 생각했다. 그래서 지금 당장은 하드코딩으로 구현했다.

💭 고민 -(2) 이미지 저장을 image 폴더에 vs 외부 저장소

image 폴더에 저장하게 된 이유

• image 폴더에 저장하게 된다면?
  docs 에 들어가는 이미지들을 리액트 내에 저장하게 된다면 이미지 최적화를 하더라도 빌드 크기가 커져 빌드 속도가 늘어나고 git 저장소의 크기가 커져 pull 받을때의 시간 또한 늘어날 것이다.

하지만 이 이유 때문에 이미지를 배포하기에는 이것 또한 오버엔지니어링 이라고 판단했다.

• 외부 저장소 이용 기준
  보통 이미지들의 크기가 5~10M 이상일 때 외부 저장소 이용을 고려한다고 한다.

아래 명령어를 통해 docs 폴더의 이미지 파일 크기를 확인했다.

du -ch images/docs/*.{jpg,jpeg,png,gif,webp} | grep total | cut -f1

그 결과 4.1M 라는 결과가 나왔다.
생각보다 좀 많긴한데, 5M 이하여서 배포는 하지 않기로 했다.

대신 외부 저장소를 사용할 수 있을것이라는 것을 고려해야한다고 생각해서

/**
 * 
 * export const DOCS_IMAGES = {
  checkBranchCreated: `${S3_BASE_URL}/check-branch-created.png`,
  추후 이미지 배포 시 다음과 같이 url을 넣어주어 사용할 수 있습니다. 
};
 */
export const DOCS_IMAGES = {
  checkBranchCreated,
  createBranch,
  checkBranchCreatedWebp,
  createBranchWebp,
  createRoomWebp,
  selectMissionWebp,
  startWithMissionWebp,
  ...
};

다음과 같이 이미지들을 한 파일에 모아주었다. 이 부분의 url 만 수정하면 한 파일 수정만으로 외부 이미지 사용이 가능하다.

+) 코딩해듀오의 프론트엔드 서버를 ec2 -> s3 로 전환하여 이미지 cdn 캐싱 또한 쉽게 가능해졌다. 따라서 cdn 캐시는 고려하지 않으려고 한다!!

간단한 성능 개선

• 이미지 lazy loading
  이미지가 많을때 첫 로딩 시 모든 이미지를 로딩하게 된다면 시간이 오래 걸려 사용자 이탈이 생길 수 있다. 하지만 위에서 말했듯 이미지 용량이 크지 않아서 intersection Observer 로 화면에 맞게 lazy 로딩을 하지는 않았고 img 태그에 속성 추가로 간단하게만 지정해주었다.
• 이미지 포맷, 이미지 resize
  docs 에 필요한 이미지들을 다음 명령어를 통해 모두 webp 로 바꿔주었고,

for file in *; do cwebp "$file" -o "${file%.*}.webp"; done 

imagemagick 이라는 라이브러리의 도움을 받아 이미지를 70% 축소했다.

for file in *; do magick $file -resize 70% $file; done

webp 를 지원하지 않는 브라우저에서는 png 를 사용할 수 있도록 img 태그도 넣어주었다.

 <picture>
        <source srcSet={webpSrc} type="image/webp" />
        <img src={src} alt={alt} loading="lazy" />
      </picture>

• 개선 결과
  <이전>
  

  <이후>
  

구현

컴포넌트 요약 - PR 확인하기

요구사항

구현해야 하는 부분에 대해 요구사항을 정리해보았다.

• 사이드바에 있는 목록을 클릭하면 해당하는 섹션으로 스크롤이 이동해야한다.

• 외부에서 해당 섹션의 스크롤 위치로 이동할 수 있어야 한다.

• 스크롤 시 사이드바의 목록에서 현재 목록이 활성화 되어야 한다.

• styled component 와 커스텀 한 컴포넌트를 이용해 쉽게 내용 추가가 가능해야한다.
  -> 커스텀 한 컴포넌트는 스토리북 배포를 참고할 수 있도록 했다.
  스토리북

스크롤 이벤트 구현

(1) 초기 시안
외부에서 해당 스크롤 위치로 이동할 수 있으려면 url에 해시값이 있어야 한다고 판단했다.
그래서 sidebar 는 해시값을 가져와 active 상태를 결정하고
메인docs 에서는 해시값에 따라 스크롤 위치가 조정, 화면의 50% 이상 부분에 섹션이 나타나면 url 해시값이 변경되도록 했다.

여기서 다음과 같은 문제가 나타났다.

• 사이드바 컨텐츠 클릭 시 해당 컨텐츠로 스크롤 된다.
• 스크롤 시 해당 컨텐츠가 50% 이상 화면에 나왔을 때 url 해시값이 변경된다.
  → 이 두 기능이 충돌해서 3의 위치에서 1을 클릭했을때 2 컨텐츠가 화면에 나올때 url 이 변경되어 스크롤 이동이 멈추게 된다.
  → 또, 아래로 스크롤 할 때는 인식이 되지만, 위로 스크롤 하면 적용되지 않는다.

이를 해결하기 위해 다음과 같은 고민을 했다.
1. 내부에 currentSection 상태를 추가하여 따로 관리하기
2. 스크롤이 다 된 후에 위치 인식하도록 하기

2번은

if (element) {
        isScrollingRef.current = true;
        element.scrollIntoView({ behavior: 'smooth' });
        setTimeout(() => {
          isScrollingRef.current = false;
        }, 100);
      }

를 통해 isScrollingRef.current 가 false 일 때만 화면 인식이 될 수 있도록 구현할 수 있었다. 하지만 setTimeout 으로 부자연스럽게 순서를 지정해주는게 불필요한 사이드이펙트를 만드는 것이라고 생각해서 1번의 방법을 채택하기로 했다.

(2) 1단계 개선
sidebar 는 active section 을 props 로 받아 활성화 하고, 대신 컨텐츠 클릭 시 해당 부분으로 해시값 변경
메인docs 에서는 해시값에 따라 스크롤 위치가 조정, 스크롤 하면 active section 상태가 변경

이렇게 해당 버그를 해결했다.

이제 스크롤 인식이 잘 되지 않는 버그를 해결해야한다.

내용이 담긴 섹션이 화면에 나타난다면 활성화 되도록 구현이 되어있는데, 이렇게 하면 1번 섹션과 2번 섹션의 사이에 있을 때 어떤 섹션을 활성화 할 지 몰라서 인식이 되지 않는 듯 하다.

(3) 2단계 개선
그래서 섹션의 title에만 id 를 넣었다.
대신 가장 외부의 container에 aria-labelledby를 넣어 한 섹션임을 명시해주었다.

빠르게 스크롤을 하거나 위로 스크롤을 해도 인식이 잘 됐다.

최종 코드 scroll

const useHashScroll = () => {
  const location = useLocation();
  const currentHash = location.hash.replace('#', '');
  const [activeSection, setActiveSection] = useState(currentHash);
  const isProcessingRef = useRef(false);

  const handleActiveSection = (section: string) => setActiveSection(section);

  /**
   * 스크롤 이벤트를 감지하여 현재 뷰포트에 보이는 섹션의 id 값에 따라 activeSection 업데이트
   * - 요소가 뷰포트에 진입하는 순간 활성화
   * - 요소가 뷰포트 상단에서 보이기 시작하는 순간부터 하단에 도달하기 직전까지의 모든 위치를 포함
   * - isProcessingRef 를 통해 진행중일때 불필요한 계산을 하지 않도록 함.
   */
  useEffect(() => {
    const handleScroll = () => {
      if (isProcessingRef.current) return;

      requestAnimationFrame(() => {
        const sections = Array.from(document.querySelectorAll<HTMLElement>('section[id], div[id], p[id]'));
        const viewportHeight = window.innerHeight;

        const visibleSection = sections.find((section) => {
          const rect = section.getBoundingClientRect();
          return rect.top >= 0 && rect.top <= viewportHeight;
        });

        if (visibleSection && visibleSection.id !== activeSection) {
          handleActiveSection(visibleSection.id);
        }

        isProcessingRef.current = false;
      });

      isProcessingRef.current = true;
    };

    window.addEventListener('scroll', handleScroll);

    return () => {
      window.removeEventListener('scroll', handleScroll);
    };
  }, [activeSection]);

  /**
   * url 의 해시값을 기반으로 스크롤 이동
   */
  useEffect(() => {
    if (location.hash) {
      const element = document.getElementById(currentHash);
      if (element) {
        element.scrollIntoView({ behavior: 'smooth' });
      }
    }
  }, [location]);

  return { activeSection };
};

export default useHashScroll;

앞으로 개선할 일

light house 와 퍼포먼스 탭에서 CPU 6x 감소 한 후 성능을 측정해봤다.

추후 긴 작업시간이 나온 부분을 분석 후 개선해 보도록 할 예정이다.