개발

[사람별] Next.js 에러 핸들링 (error.tsx)

채._. — Sat, 26 Apr 2025 23:07:20 +0900

문제 상황

Next.js를 사용해 캘린더 페이지를 개발하는 중,
Supabase 통신 중 발생하는 에러를 페이지 라우터 세그먼트 내의 error.tsx로 통합해서 처리하려 했다.

하지만 에러를 던질 때 내가 지정한 메시지와 런타임 중 발생하는 시스템 메시지가 섞여 나오는 문제가 있었다.

또한,

app/api/**/route.ts (라우트 핸들러)
supabase 호출 함수(fetch)
클라이언트 컴포넌트 (page.tsx)
탠스택 쿼리(useQuery)

이렇게 여러 레이어를 거치면서 에러 흐름을 깔끔하게 잡는 것도 고민이 필요했다.

최종적인 에러 흐름은 아래와 같다.

라우트 핸들러

성공or에러를 객체 형태로 받아서 return 페이지에서 에러 객체를 잡아서 throw error.tsx 잡음

import ENV from '@/constants/env.constant';
import { NextResponse } from 'next/server';

// 공휴일 라우트 핸들러
export async function GET(req: Request) {
  const { searchParams } = new URL(req.url);
  const year = searchParams.get('year') || new Date().getFullYear().toString();

  try {
    const url = `${ENV.HOLIDAY_URL}/getRestDeInfo?ServiceKey=${ENV.HOLIDAY_KEY}&solYear=${year}&_type=json&numOfRows=100`;
    const res = await fetch(url);

    if (!res.ok) {
      throw new Error(`공휴일 API 응답 오류: ${res.statusText}`);
    }

    const data = await res.json();
    // 데이터 구조 검증
    if (!data.response || !data.response.body) {
      console.error('유효하지 않은 API 응답 형식:', data);
      return NextResponse.json({ error: '공휴일 데이터 형식이 올바르지 않습니다' }, { status: 500 });
    }
    return NextResponse.json(data); //정상 응답 반환
  } catch (error) {
    console.error('공휴일 데이터 호출 중 오류 발생:', error);
    return NextResponse.json({ error: '공휴일을 불러올 수 없습니다' }, { status: 500 });
  }
}

supabase 통신

각 통신 함수에서 console.error & throw new Error 페이지 내의 쿼리 훅에서 error 꺼내기 각 에러 처리 후 throw error.tsx 잡음

1. plans 데이터 불러오기
export const getPlans = async (planId: string): Promise<PlansType> => {
  const { data, error } = await supabase.from(PLANS).select('*').eq('plan_id', planId).single();

  if (error) {
    console.error('약속을 불러오는 중 오류가 발생했습니다:', error);
    throw new Error('약속을 불러오는 중 문제가 발생했습니다. 다시 시도해주세요.');
  }

  return data;
};

2. 쿼리 훅에서 error 꺼내기
  const { data: holidays, error: holidaysError } = useGetHolidays(String(calendarYear)); //공휴일
  const { data: events, isPending, error: plansError } = useGetCalendarPlans(user, calendarYear, moment); //약속(readonly)
  const {
    data: selectedPlanData,
    error: selectPlanError,
    refetch: refetchSelectedPlan,
  } = useGetSelectPlan(selectedPlanId ?? '');
    const { mutate: updateEvent, error: updatePlanError } = useUpadateEventMutate();
    
    
3. 에러 모아서 throw
  if (holidaysError || plansError || selectPlanError || updatePlanError) {
    const error = new Error('캘린더 데이터를 불러오는 중 문제가 발생했습니다.') as Error & {
      originalError?: Error | null;
    };
    error.originalError = holidaysError ?? plansError ?? selectPlanError ?? updatePlanError;
    throw error;
  }

에러 흐름 전체 구조

에러 처리를 다음과 같은 규칙으로 정리했다.

1. 라우트 핸들러(app/api//route.ts)**

서버 사이드에서 에러 발생 시 → NextResponse.json({ error }, { status }) 로 클라이언트에 에러 전달

return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 });

2. 통신 로직 (Supabase 호출 함수 등)

fetch 함수에서는 통신 실패 시 throw new Error('커스텀 메시지') 로 에러 던지기

이때 통신 자체가 안 된다면 런타임 에러가 발생할 수 있으니 주의.

if (error) {
  throw new Error('약속을 불러오는 중 오류가 발생했습니다.');
}

3. 페이지 컴포넌트 (ex. app/(routes)/calendar/page.tsx)

직접적인 오류 발생 시 throw new Error('메시지') → error.tsx로 연결되도록 설정

if (!data) {
  throw new Error('데이터를 불러올 수 없습니다.');
}

4. 탠스택 쿼리 (useQuery, useMutation)

쿼리 훅 내부에서는 Next.js의 error.tsx를 직접 건드리지 않고
error, isError 플래그를 통해 클라이언트 컴포넌트 안에서 에러 처리

const { data, error, isError } = useGetCalendarPlans();

if (isError) {
  throw error;
}

✅ 흐름 정리

라우트 핸들러에서 발생하는 에러는 json 응답으로 내려옴
통신(fetcher) 단에서 받은 에러는 throw new Error로 명시적으로 던짐
페이지 컴포넌트에서는 통합적으로 에러를 받아 필요한 경우 다시 throw
최종적으로 error.tsx가 모든 에러를 받아 처리하는 구조

error.tsx

error.tsx에서는 이렇게 메인 에러와 서브 에러(originalError)를 나누어 출력했다.

메인 에러: 캘린더 페이지에서 throw한 메세지 '캘린더 데이터를 불러오는 중 문제가 발생했습니다.'
서브 에러: supabase 통신 로직에서 throw한 디테일 메세지 '약속을 불러오는 중 오류가 발생했습니다. 다시 시도해주세요'

에러를 콘솔에도 출력해서 디버깅하기 쉽게 설정했다.

'use client';

import GenericError from '@/components/Error';

export default function ErrorPage({ error, reset }: { error: Error & { originalError?: Error }; reset: () => void }) {
  console.error('메인 에러:', error);

  if (error.originalError) {
    console.error('원래 에러:', error.originalError);
  }

  return (
    <GenericError
      error={error}
      originalError={error.originalError ?? null}
      refetch={reset} // reset 함수는 Next.js가 제공하는 재시도 함수
    />
  );
}

GenericError 컴포넌트

렌더링 시, error.message와 originalError.message 를 각각 보여줄 수 있도록 했다.

import { Warning } from '@phosphor-icons/react';

type GenericErrorProps = {
  error?: Error | null;
  originalError: Error | null;
  refetch?: () => void;
};

export default function GenericError({ error, refetch, originalError }: GenericErrorProps) {
  return (
    <div className='flex min-h-screen flex-col items-center justify-center gap-8'>
      <Warning size={60} className='text-secondary-600' />
      <h2 className='title text-[45px] font-bold text-primary-700'>Error!</h2>
      {error?.message && originalError?.message && (
        <section className='flex flex-col items-center text-[23px] text-primary-500'>
          <p>{error?.message}</p>
          <p>Detail: {originalError?.message}</p>
        </section>
      )}
      {refetch && (
        <button
          onClick={refetch}
          className='rounded-md border-2 bg-primary-500 p-4 font-bold text-white hover:bg-primary-600'
        >
          다시 시도
        </button>
      )}
    </div>
  );
}

일부러 통신 에러를 만드는 방법

Supabase 요청 중 발생하는 에러는 잘 잡히지만,
코드 자체에서 런타임 에러가 나면 Supabase에 도달조차 못 하고 죽는다.

예를 들면 아래와 같이 Supabase 요청을 보내기도 전에 런타임 에러가 발생한다.
(따라서 originalError가 존재하지 않는다.)

const { error } = await supabase.from(PLAS).select('*'); // PLAS가 undefined

따라서 Supabase 통신 실패를 일부러 만들고 싶으면

잘못된 테이블명 사용
필수 컬럼을 누락
존재하지 않는 필드를 쿼리

등을 통해 에러를 발생시키고,
정상적으로 응답이 오게 한 뒤 거기서 error 체크 후 던지는 식으로 처리해야 한다.

최종 결과 및 느낀점

이번 작업을 통해 런타임 에러와 통신 에러를 명확히 구분해서 다뤄야 한다는 걸 다시 깨달았다.

또한 throw new Error를 쓰는 위치, 에러를 받는 위치(error.tsx), 표시하는 방법(GenericError 컴포넌트)까지 모두 설계해야
에러 핸들링이 완성된다는 것을 경험했다.

[사람별_Day10] 월별로 데이터 캐싱하기

채._. — Wed, 9 Apr 2025 23:45:29 +0900

오전 스크럼 시간에 캘린더 구현 기능을 이야기 나누던 중, 튜터님의 한 마디

"약속 데이터는 한 번에 다 받아오나요? 월별로 넘어갈 때마다 데이터를 가져오는 건 어떨까요?"

테스트 단계인 지금은 임의의 값 두어 개만 넣어놓고 전체를 가져오기 때문에 크게 문제가 안 되겠지만,

실제로 이 서비스가 활성화된다면..

여러 유저가 약속 일정을 추가하게 되고, 시간이 지나 아주 예전 데이터까지 다 불러오게 된다면...

안 되겠다. 매 달마다 데이터를 가져오고 캐싱해두어야겠다.

월별 데이터 캐싱하기

간단히 설명하자면 캘린더 컴포넌트 - useQuery 커스텀 훅 - supabase 데이터 페칭 함수 세 로직의 관계를 수정하면 된다.

캘린더 컴포넌트

캘린더 컴포넌트의 역할은 다음과 같다.

해당 달의 상태 관리 - Date 객체 : Wed Apr 09 2025 23:37:00 GMT+0900 (한국 표준시)
해당 달의 현재 년도 - number : 2025
useQuery 커스텀 훅에 년도와 달의 값 넘겨주어 데이터 받아오기 : 약속 일정 데이터

  const [month, setMonth] = useState(new Date()); //해당 달 
  const calendarYear = month.getFullYear(); // 해당 달의 년도
  const { data: events, isPending, isError, error } = useGetCalendarPlans(calendarYear, month);

useQuery 커스텀 훅

useQuery 커스텀 훅의 역할은 다음과 같다.

supabase에 숫자로 전달해주기 위해 타입 전환
해당 년도의 달마다 캐싱 (staleTime은 1일)
supabase 페칭 로직에 년도와 달 넘겨주어 값 가져오기
받아온 데이터를 캘린더에 적용하도록 가공하기

export const useGetCalendarPlans = (year: number, monthDate: Date) => {
  const month = monthDate.getMonth() + 1; // Date 객체 -> 숫자 전환
  return useQuery<CalendarEventType[]>({
    queryKey: [QUERY_KEY.CALENDAR_PLANS, year, month], //달마다 캐싱
    queryFn: async () => {
      const plans: PlansType[] = await getPlans(year, month); // supabase에서 plans 데이터 가져오기

      // 캘린더에 적용되도록 데이터 가공하기
      const events: CalendarEventType[] = plans.map((plan) => ({
        id: plan.plan_id,
        title: plan.title,
        start: new Date(plan.start_date),
        end: new Date(plan.end_date),
      }));
      return events;
    },
     staleTime: 24 * 60 * 60 * 1000, // 1일
  });
};

supabase 데이터 페칭 함수

supabase 데이터 페칭 함수의 역할은 다음과 같다.

매 달의 첫 날과 마지막 날 만들기
약속 추가할 때 1시간 추가한 이유
- DnD 시 단일 일정 늘어남 (end-start = 0 일 때 자동처리)
- 연속 일정 시 마지막 날 달력에 적용시키기
월말~월초 이어지는 약속도 나타내기 위해 setHours 적용
lte: 작거나 같다 / gte: 크거나 같다

export const getPlans = async (year: number, month: number): Promise<PlansType[]> => {
  const startOfMonth = new Date(year, month - 1, 1); //첫 날
  const endOfMonth = new Date(year, month, 0); //마지막 날 (4/30 00:00:00)
  // 현재 start_date가 4/30 01:00 이기 때문에 연속 일정의 첫 날도 함께 포함시키기 위함
  endOfMonth.setHours(23, 59, 59, 999);

  const { data: plans, error } = await supabase
    .from(PLANS)
    .select('plan_id, user_id, contacts_id, title, detail, priority, start_date, end_date')
    //해당 달의 데이터만 가져오기(넘어가는 연속 일정 포함)
    .lte('start_date', endOfMonth.toISOString()) // 일정이 달의 마지막 날과 같거나 이전에 시작
    .gte('end_date', startOfMonth.toISOString()); // 일정이 달의 첫 날보다 같거나 이후에 끝
  if (error) {
    throw new Error(error.message);
  }
  return plans;
};

[사람별_Day9] 공휴일 달력에 적용하기 (feat.공공데이터)

채._. — Wed, 9 Apr 2025 23:12:35 +0900

달력이라면 필요한 공휴일 !

공공데이터 API 발급

공휴일 정보를 얻어오기 위해서 공공데이터를 이용하였다.

회원가입과 로그인을 하고 활용신청을 클릭한다.

신청이 완료되면 일반 인증키 두 개가 발급되는데, Encoding 키를 이용하였다.

API 적용

라우트 핸들러

.env.local 파일에 키 값을 둘 때 한 가지 유의할 점이 있다.

supabase의 어논키 같은 경우는 브라우저에 노출되어도 크게 문제가 안 되기 때문에 'NEXT_PUBLIC'을 붙여서 사용한다.

하지만 공공데이터 같은 경우는 회원가입 후 발급받았기 때문에 브라우저에 노출이 조금 꺼려졌다.

따라서 'NEXT_PUBLIC'을 사용하지 않았다.

const ENV = {
  SUPABASE_URL: process.env.NEXT_PUBLIC_SUPABASE_URL || '',
  SUPABASE_ANON_KEY: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY || '',
  HOLIDAY_KEY: process.env.HOLIDAY_KEY || '',
};

export default ENV;

그렇다면 이 키를 사용해서 어떻게 데이터를 불러와야 할까?

처음에는 기존 방식을 따라 service.ts 파일에서 fetch를 통해 다음과 같이 가져왔었다.

// 공공데이터 공휴일 API
export const getHolidays = async (year: string) => {
  const BASE_URL = 'http://apis.data.go.kr/B090041/openapi/service/SpcdeInfoService';
  const res = await fetch(
    //현재 년도 값만
    `${BASE_URL}/getRestDeInfo?ServiceKey=${ENV.HOLIDAY_KEY}&solYear=${year}&_type=json&numOfRows=100`
  );
  const data = await res.json();

  return data;
};

하지만 'NEXT_PUBLIC'가 없기 때문에 브라우저에서의 사용이 불가능했다.

따라서 생각한 것이 라우트 핸들러!

서버-서버의 통신을 통해 데이터의 응답 값을 라우트 경로에 주기 때문에

서버에서 키 값 사용하여 데이터 페칭이 가능하며 그 데이터를 브라우저에서도 사용이 가능하다.

공휴일 API 라우트 핸들러

// app > api > holiday > route.ts
import { NextResponse } from 'next/server';

// 공휴일 라우트 핸들러
export async function GET(req: Request) {
  const { searchParams } = new URL(req.url);
  const year = searchParams.get('year') || new Date().getFullYear().toString();

  const BASE_URL = 'http://apis.data.go.kr/B090041/openapi/service/SpcdeInfoService';
  const HOLIDAY_KEY = process.env.HOLIDAY_KEY;

  const url = `${BASE_URL}/getRestDeInfo?ServiceKey=${HOLIDAY_KEY}&solYear=${year}&_type=json&numOfRows=100`;

  const res = await fetch(url);
  const data = await res.json();

  return NextResponse.json(data);
}

데이터 가공

라우트핸들러를 통해 받아온 응답값을 fetch로 받아온다.

export const useGetHolidays = (calendarYear: string) => {
  // 공휴일 데이터 전체 가져오기
  const fetchHolidays = async () => {
    const res = await fetch(`/api/holidays?year=${calendarYear}`); // 년도에 맞는 데이터
    const data = await res.json();
    const items = data.response?.body?.items?.item || [];
    
    ...

이 값은 달력에 바로 적용할 수 없으므로 알맞게 가공해야 한다.

1. 필요한 값만 추출

초기 데이터에서 필요한 날짜와 공휴일명을 뽑아낸다.

// 필요한 값만 추출
    const holidays = items.map((item: Item) => ({
      date: item.locdate, // 20250408 형식
      name: item.dateName,
    }));

2. 달력에 적용할 수 있도록 가공

.slice 메서드를 사용하기 위해 숫자였던 date를 문자열로 변환하여 dateStr 변수에 담아준다.
'20250101' 형태의 date를 년, 월, 일로 나누어 new Date 객체로 변환한다.
- 이때, 월은 0부터 시작하는 인덱스이기 때문에 '-1' 처리를 해준다.

 // 캘린더에 적용할 수 있도록 가공
    const formattedHolidays = holidays.map((item: Holidays) => {
      const dateStr = item.date.toString(); // number → string

      return {
        title: item.name,
        date: new Date(
          parseInt(dateStr.slice(0, 4), 10), // year
          parseInt(dateStr.slice(4, 6), 10) - 1, // month (0-indexed)
          parseInt(dateStr.slice(6, 8), 10) // day
        ),
      };
    });
    return formattedHolidays;
  };

3. useQuery 훅을 반환

이 모든 기능의 함수를 queryFn로 갖는 useQuery를 생성한다.
공휴일의 정보를 년마다 캐싱하기 위해 쿼리 키를 해당 년도에 따라 동적으로 변동한다.

 return useQuery({
    queryKey: [QUERY_KEY.HOLIDAYS, calendarYear], // 년도에 따라 쿼리키 변동
    queryFn: fetchHolidays,
    staleTime: 1000 * 60 * 60 * 24, // 1일
  });

useQuery 커스텀 훅 전체 로직

import { QUERY_KEY } from '@/constants/queryKey';
import { Holidays, Item } from '@/types/plans';
import { useQuery } from '@tanstack/react-query';

export const useGetHolidays = (calendarYear: string) => {
  // 공휴일 데이터 전체 가져오기
  const fetchHolidays = async () => {
    const res = await fetch(`/api/holidays?year=${calendarYear}`); // 년도에 맞는 데이터
    const data = await res.json();
    const items = data.response?.body?.items?.item || [];

    // 필요한 값만 추출
    const holidays = items.map((item: Item) => ({
      date: item.locdate, // 20250408 형식
      name: item.dateName,
    }));

    // 캘린더에 적용할 수 있도록 가공
    const formattedHolidays = holidays.map((item: Holidays) => {
      const dateStr = item.date.toString(); // number → string
      return {
        title: item.name,
        date: new Date(
          parseInt(dateStr.slice(0, 4), 10), // year
          parseInt(dateStr.slice(4, 6), 10) - 1, // month (0-indexed)
          parseInt(dateStr.slice(6, 8), 10) // day
        ),
      };
    });
    console.log('formattedHolidays', formattedHolidays);
    return formattedHolidays;
  };

  return useQuery({
    queryKey: [QUERY_KEY.HOLIDAYS, calendarYear], // 년도에 따라 쿼리키 변동
    queryFn: fetchHolidays,
    staleTime: 1000 * 60 * 60 * 24, // 1일
  });
};

달력에 공휴일 적용

이제 달력에 적용할 수 있도록 가공한 데이터를 적용해야 한다.

캘린더 컴포넌트에서 다음과 같이 상태와 값을 정의하고 있다.

커스텀 훅에 해당 년도를 문자열로 넣어주고 그 값을 'holidays'라는 이름으로 받아온다.

  const [month, setMonth] = useState(new Date()); //해당 달
  const calendarYear = month.getFullYear(); // 해당 달의 년도
  const { data: holidays } = useGetHolidays(String(calendarYear)); // useQuery 커스텀 훅

기존에 나타내었던 약속 일정들과 공휴일을 하나의 배열로 합쳐서 달력에 전달해주어야 한다.

기존 약속인 event를 펼친다.
공휴일 데이터인 holidays을 기존 약속과 같은 이름으로 매핑하여 펼친다.
둘을 하나의 배열로 만든다.

  // 약속 + 공휴일
  const combinedEvents: CalendarEventType[] = [
    ...(events || []),
    ...(holidays || []).map((holiday: Holidays, idx: number) => ({
      id: `holiday-${idx}`,
      title: holiday.title,
      start: holiday.date,
      end: holiday.date, // 단일 일정
      isHoliday: true, // 스타일 구분용
    })),
  ];

최종적으로 캘린더에 적용하면 완료!

   <DnDCalendar
        localizer={localizer}
        events={combinedEvents}
        ...
    />

[사람별_Day8] RBC 쪼개기 1 - CustomToolbar : 날짜 이동

채._. — Mon, 7 Apr 2025 17:31:46 +0900

시작 요일, 월간만 보여주기

월요일부터 시작

const localizer = dateFnsLocalizer({
  format,
  parse,
  startOfWeek: () => startOfWeek(new Date(), { weekStartsOn: 1 }), // 월요일 시작
  getDay,
  locales,
});

월간만 보여주기

   <Calendar
        localizer={localizer}
        events={events} // 여기에 이벤트 추가 가능
        startAccessor='start'
        endAccessor='end'
        defaultView='month' // 기본 보여주기 : 월별
        views={['month']} // 월간 달력만 보여주기
        style={{ height: 500 }}
      />

RBC 주요 컴포넌트

좌측 상단에 날짜 넘기기 / 오늘 날짜 버튼을 두어 달력의 이동을 구현하고 싶었다.

사례를 찾다보니 RBC의 요소들을 여러 컴포넌트로 쪼개서 사용할 수 있다는 것을 알게되었다.

쪼갤 수 있는 주요 컴포넌트는 다음과 같다.

components={{
  toolbar,           // 상단 툴바
  event,             // 이벤트 셀
  agenda: {
    event,           // agenda view의 이벤트
  },
  timeSlotWrapper,   // 시간 슬롯 (시간 칸)
  dateCellWrapper,   // 날짜 셀 (월간 뷰 셀)
  day,               // 일간 뷰
  week,              // 주간 뷰
  month,             // 월간 뷰
}}

Toolbar의 props

그 중 툴바에 해당하는 요소를 자세히 살펴보겠다.

label, onNavigate, localizer, onView, date, view, views

label

툴바 중앙에 보통 보이는 현재 날짜 범위의 텍스트 (예: "April 2025")
RBC 내부에서 자동으로 만들어줌

<span>{label}</span>  // "April 2025"

onNavigate(action)

이전/다음/오늘 버튼 클릭 시 사용하는 함수
action 값은 다음 중 하나: 'PREV', 'NEXT', 'TODAY', 'DATE'

<button onClick={() => onNavigate('TODAY')}>Today</button>
<button onClick={() => onNavigate('PREV')}>{'<'}</button>
<button onClick={() => onNavigate('NEXT')}>{'>'}</button>

localizer

달력에서 사용하는 날짜/시간 관련 기능들을 지역(locale)에 맞게 처리
날짜를 "2025년 4월 7일"처럼 포맷
요일을 "Mon", "Tue"가 아니라 "월", "화"처럼 변경
주의 시작 요일을 월요일로 설정

onView(viewName)

뷰(예: month, week, day, agenda)를 전환하고 싶을 때 사용하는 함수
views props에 해당 뷰가 등록되어있어야 작동한다.

<button onClick={() => onView('month')}>Month</button>
<button onClick={() => onView('week')}>Week</button>

date

현재 보여지고 있는 캘린더 날짜 기준의 Date 객체 (예: 2025-04-01)
직접 날짜 조작하고 싶을 때 유용

view

현재 보고 있는 뷰의 이름 ('month', 'week', 'day', 'agenda')

if (view === 'month') {
  // 월간 뷰 전용 UI 보여주기
}

views

사용 가능한 뷰들의 배열 (예: ['month', 'week', 'day'])
이걸로 view 전환 버튼을 동적으로 생성할 수 있다.

이전, 다음 달 넘기기

onNavigate()와 date를 사용한다.

공식 문서에서는 onNavigate와 date를 다음과 같이 설명하고 있다.

둘은 함께 사용되며 onNavigate 함수를 통해 date를 제어하는 것이다.

동적으로 변하는 날짜를 state로 두고 onNavigate 함수로 이를 제어했다.

// MainCalendar.tsx

const MainCalendar = () => {
  const [month, setMonth] = useState(new Date());
  
  return (
    <div>
   	 <Calendar
        localizer={localizer}
        events={events}
        date={month} // 현재 날짜(달)
        onNavigate={(newDate) => {
          setMonth(newDate); // 날짜(달) 변동
        }}
        startAccessor='start'
        endAccessor='end'
        defaultView='month'
        views={['month']}
        components={{
          toolbar: CustomToolbar, // 상단 툴바 분리
        }}
        style={{ height: 500 }}
      />
    </div>
  );
};

// CustomToolbar.tsx

import React from 'react';
import { NavigateAction } from 'react-big-calendar';

interface Props {
  label: string;
  onNavigate: (action: NavigateAction) => void;
}

const CustomToolbar = ({ label, onNavigate }: Props) => {
  return (
    <div>
      <button onClick={() => onNavigate('PREV')}>⬅️</button>
      <span>{label}</span>
      <button onClick={() => onNavigate('NEXT')}>➡️</button>
      <button onClick={() => onNavigate('TODAY')}>Today</button>
    </div>
  );
};

export default CustomToolbar;

버튼은 CustomToolbar 안에 있는데 외부에 date랑 onNavigate를 두어도 작동되는 이유가 뭘까?

캘린더 컴포넌트가 툴바에게 props를 넘겨주기 때문에 둘이 연결될 수 있는 것이다.

좀 더 자세히 살펴보자면,

<Calendar
  date={month}                          //   현재 날짜 state
  onNavigate={(newDate) => setMonth(newDate)} //   날짜 변경 함수
  components={{ toolbar: CustomToolbar }}      //   커스텀 툴바 적용
/>

사용자가 버튼을 클릭한다.
CustomToolbar에서 onNavigate('PREV')
RBC 자체적으로 PREV에 맞는 newDate 계산
Calendar의 onNavigate(newDate) 호출
Calendar의 setMonth(newDate) → state 업데이트
Calendar 다시 렌더링 + CustomToolbar도 리렌더링

localizer 설정 : 2025 4월

사실 최상단에 정리한 것처럼 툴바가 아닌 캘린더에서 월요일 시작을 구현했다.

따라서 캘린더에서와 툴바에서의 localizer 역할 차이도 궁금했다.

캘린더에서의 localizer

전체 캘린더의 날짜 처리 기준을 정한다.

<Calendar localizer={localizer} ... />

기본 날짜 포맷팅, 시작 요일, 언어/로케일, 날짜 계산 로직 등을 Calendar에 전달
내부적으로 localizer.format(...), localizer.startOfWeek(...) 등을 사용해서 날짜 처리
시작 요일을 월요일: startOfWeek: () => startOfWeek(new Date(), { weekStartsOn: 1 })

툴바에서의 localizer

툴바에 표시되는 날짜 텍스트 포맷한다.

const CustomToolbar = ({ localizer }: ToolbarProps<Event>) => {
  const label = localizer.format(date, 'yyyy MMMM', 'ko-KR');
};

Calendar에서 넘겨준 localizer 객체가 툴바에도 전달
툴바는 보통 현재 날짜에 맞는 문자열(label) 을 표시하기 때문에,
localizer.format(...) 을 직접 호출해서 사용자가 보기 쉬운 텍스트를 만든다.
"2025년 4월" 한글로 표시하고 싶을 때 : 직접 format을 호출해서 처리

지금 필요한 건 날짜를 "2025년 4월"처럼 포맷 하는 기능이다.

localizer.format(date, formatString, culture)을 사용하여 원하는 형태로 날짜 출력 가능하다.

하지만,

캘린더에 const localizer = dateFnsLocalizer() 명시도 하고, 툴바에도 맞게 적용했지만 계속해서 'message' 오류가 발생했다.

원인은 dateFnsLocalizer()로 생성한 localizer와 Calendar의 generic 타입이 서로 안 맞아서 생기는 문제이다.

사실 그 내용을 아주 자세히 파악하지 못했지만 대략 다음과 같이 이해했다.

캘린더에서는 id가 포함된 supabase 데이터를 사용하기 때문에 CalendarEventType(id 포함) 타입을 사용하지만,
툴바에는 id를 사용하지 않는다. 따라서 둘의 타입이 맞지 않아서 생기는 문제

따라서 문제를 다음과 같이 해결하였다.

툴바의 타입을 캘린더와 같게 명시해주기 => 캘린더의 components > toolbar 에서 타입 오류 사라짐
date-fns에서 한글 날짜값 가져오기

import { CalendarEventType } from '@/types/plans';
import { format } from 'date-fns';
import { ko } from 'date-fns/locale';
import { ToolbarProps } from 'react-big-calendar';

//⭐️캘린더와 타입 맞춤(id 유실로 인한 오류)⭐️ 
const CustomToolbar = ({ date, onNavigate }: ToolbarProps<CalendarEventType>) => {
  const customLabel = format(date, 'yyyy MMMM', { locale: ko });
  return (
    <div>
      <button onClick={() => onNavigate('PREV')}>⬅️</button>
      <span>{customLabel}</span>
      <button onClick={() => onNavigate('NEXT')}>➡️</button>
      <button onClick={() => onNavigate('TODAY')}>Today</button>
    </div>
  );
};

export default CustomToolbar;

어차피 커스터마이징 하는 것이기 때문에 꼭 localizer에 얽메이지 않고 date-fns에서 한글로 맞게 번역하는 방법을 택했다.

[사람별_Day8] Tanstack Query 초기 로딩 처리 - initialData

채._. — Sun, 6 Apr 2025 23:43:56 +0900

이전 상황 : Tanstack Query 적용 중 undefined 방지

useEffect로 처리했던 이전 로직을 tanstack으로 관리하기 위해 커스텀 훅으로 뺐다.

아래 로직은 formatted 로직을 제외한, supabase에서 데이터를 받아오는 부분만 커스텀으로 뺐을 때의 로직이다.

'use client';
import { Calendar, dateFnsLocalizer } from 'react-big-calendar';
import { format, parse, startOfWeek, getDay } from 'date-fns';
import { enUS } from 'date-fns/locale/en-US';
import { ko } from 'date-fns/locale/ko';
import { useState } from 'react';
import { CalendarEventType, PlansType } from '@/types/plans';
import { useGetCalendarPlans } from '@/hooks/useGetCalendarPlans';

// 로케일(지역화) 설정
const locales = {
  'en-US': enUS, //미국-영어 : 미국식 날짜
  'ko-KR': ko, //한국-한글 : 한국식 날짜
};

const localizer = dateFnsLocalizer({
  format,
  parse,
  startOfWeek,
  getDay,
  locales,
});

const MainCalendar = () => {
  const [events, setEvents] = useState<CalendarEventType[]>([]);

  const { data: plans, isPending, isError, error } = useGetCalendarPlans();

  const fetchEvents = async () => {
    const formatted = plans.map(
      (plan: PlansType): CalendarEventType => ({
        id: plan.plan_id,
        title: plan.title,
        start: new Date(plan.start_date),
        end: new Date(plan.end_date),
      })
    );
    setEvents(formatted);
  };

  if (isPending) {
    return <div>로딩 중입니다...</div>;
  }

  if (isError) {
    return <div>캘린더 에러 발생 : {error.message}</div>;
  }

  return (
    <div>
      <Calendar
        localizer={localizer}
        events={events} // 여기에 이벤트 추가 가능
        startAccessor='start'
        endAccessor='end'
        style={{ height: 500 }}
      />
    </div>
  );
};

export default MainCalendar;

이때, plans의 값이 undefined가 될 수도 있다는 eslint의 감시가 있었다..!

이를 처리하기 위해서 useQuery에 타입을 명시함과 함께 initialData을 추가하여 초기값을 빈 배열로 주었다.

이렇게 하면 훅에서 data는 항상 PlansType[]이고, undefined가 되지 않는다.

useQuery<PlansType[]>({
  queryKey: ['calendarPlans'],
  queryFn: fetchPlans,
  initialData: [], // ✅ plans는 항상 [] 이상의 배열이 됨
});

문제 상황 : 캘린더에 일정이 나타나지 않음

하지만 문제가 발생했다.

캘린더에 일정이 나타나지 않는 다는 것이다.

어디서부터 문제가 있는 것인지 콘솔을 모두 찍어보았다.

supabase에서 데이터를 가져오는 로직, useQuery에서 적용하는 부분, 캘린더 컴포넌트

콘솔 찍은 부분들

// plans 데이터 가져오기 - calendar 사용
export const getPlans = async (): Promise<PlansType[]> => {
  const { data: plans, error } = await supabase
    .from('plans')
    .select('plan_id, user_id, contacts_id, title, detail, priority, start_date, end_date');
  console.log('getPlans: plans', plans); ⭐️
  if (error) {
    throw new Error(error.message);
  }
  return plans;
};

export const useGetCalendarPlans = () => {
  return useQuery<CalendarEventType[]>({
    queryKey: [QUERY_KEY.CALENDAR_PLANS],
    queryFn: async () => {
      const plans: PlansType[] = await getPlans(); // supabase에서 plans 데이터 가져오기
      console.log('useQuery: plans', plans); ⭐️

      // 캘린더에 적용되도록 데이터 가공하기
      const events: CalendarEventType[] = plans.map((plan) => ({
        id: plan.plan_id,
        title: plan.title,
        start: new Date(plan.start_date),
        end: new Date(plan.end_date),
      }));
      console.log('useQuery: events', events); ⭐️
      return events;
    },
    initialData: [], // undefined 아님 명시
    staleTime: 60 * 1000, // 1분
  });
};

const MainCalendar = () => {
  const { data: events, isPending, isError, error } = useGetCalendarPlans();
  console.log('MainCalendar: events', events); ⭐️

하지만 빈 배열로 찍히면서 캘린더에도 일정이 나타나지 않았다.

여러 원인을 찾으면서 시간이 좀 지나자, 갑자기 일정과 콘솔이 다시 나타났다.

뭘까.. 뭘까...

뭔가 내가 설정한 1분의 staleTime과 관련이 있을 것 같았다.

오류 원인 및 initialData 용도

처음 새로고침 시 콘솔이 찍히는 모습은 아래와 같이 빈 값(undefined)이 들어왔다가 값이 들어온다.

원인은 바로 이것이었다.

initialData 를 빈 배열로 설정해두었으니, 처음 빈 배열인 값을 캐싱해두는 것이다.

그 후 staleTime(1분)이 지나면 새롭게 값을 페칭하기 때문에 데이터가 들어오는 것이다.

즉, initialData의 용도는 새로운 값을 받아오기 전에 빠르게 값을 보여주기 위한 것이다.

서버 사이드 렌더링 데이터 있거나, 부모 컴포넌트에서 데이터 내려주는 등 진짜 초기값을 위해 쓰이게 되는 것이다.

[사람별_Day6] 캘린더에 일정 나타내기 - UTC

채._. — Fri, 4 Apr 2025 17:49:24 +0900

RBC에 대한 기본적인 기능 및 설정은 얼추 마무리되고, 실제 데이터와 연동하고자 한다.

supabase 테이블에 적용된 데이터를 가져와서 캘린더에 출력해보았다.

supabase 테이블 연결 설정은 간략히 아래와 같이 진행했다.

페이지, 컴포넌트 생성 및 연결
supabaseClient 생성 (supabaseClient.ts)
plans 테이블 값 불러오기 로직 (supabaseApi.ts)
plans 타입 지정
컴포넌트에서 호출 : useState, useEffect

new Date()

초기값을 빈 배열로 두어 이벤트 상태를 관리하였다.

하지만 state의 타입을 <plans[]>로 지정하였을 때 에러가 발생했다.

에러는 다음과 같이 나타났다.

"이 호출과 일치하는 오버로드가 없습니다. '"start"' 형식은~ , '"end"' 형식은~"

에러 원인은 supabase의 데이터 값과 RBC가 필요한 값이 다르기 때문이다.

supabase : start_date와 end_date 모두 string
RBC : start와 end 모두 Date 필요

이를 해결하기 위한 방법은 supabase의 값을 알맞게 매핑하기.

즉, Date 객체로 변환하기 위해 new Date()를 사용한다.

정리하자면

new Date() 사용 이유
1. number와 string 형식은 Date 형식에 할당할 수 없다.
2. 즉, RBC에서는 "start"와 "end" 필드가 Date 객체여야 한다.
3. Supabase에서 받아오는 start_date와 end_date의 type은 string.
4. 이 둘을 직접 Date 객체로 변환 : new Date()

state 타입은 <CalendarEvent[]>로 변경한다.

Type과 최종 로직

export interface PlansType {
  plan_id: string;
  created_at: number;
  user_id: string;
  contacts_id: string;
  start_date: string;
  end_date: string;
  title: string | null;
  detail: string | null;
  priority: string | null;
}

export interface CalendarEventType {
  id: string;
  title: string | null;
  start: Date;
  end: Date;
}

// src > components > commons > calendar.tsx

'use client';
import { Calendar, dateFnsLocalizer } from 'react-big-calendar';
import { format, parse, startOfWeek, getDay } from 'date-fns';
import { enUS } from 'date-fns/locale/en-US';
import { ko } from 'date-fns/locale/ko';
import { getPlans } from '@/lib/utils/supabaseApi';
import { useEffect, useState } from 'react';
import { CalendarEventType } from '@/types/plans';

// 로케일(지역화) 설정
const locales = {
  'en-US': enUS, //미국-영어 : 미국식 날짜
  'ko-KR': ko, //한국-한글 : 한국식 날짜
};

const localizer = dateFnsLocalizer({
  format,
  parse,
  startOfWeek,
  getDay,
  locales,
});

const MainCalendar = () => {
  const [events, setEvents] = useState<CalendarEventType[]>([]);

  useEffect(() => {
    const fetchEvents = async () => {
      try {
        const plans = await getPlans();

        const formatted = plans.map(
          (plan): CalendarEventType => ({
            id: plan.plan_id,
            title: plan.title,
            start: new Date(plan.start_date),
            end: new Date(plan.end_date),
          })
        );
        setEvents(formatted);
      } catch (error) {
        console.error('일정 목록 가져오기 에러', error);
      }
    };
    fetchEvents();
  }, []);

  return (
    <div>
      <Calendar
        localizer={localizer}
        events={events} // 여기에 이벤트 추가 가능
        startAccessor='start'
        endAccessor='end'
        style={{ height: 500 }}
      />
    </div>
  );
};

export default MainCalendar;

달력과 DB의 값 차이 : UTC

supabase 데이터 중 시작일과 종료일이 달력과 다르게 나타났다.

supabase의 데이터 타입을 timestamptz (타임스탬프 with 타임존)으로 두면

값이 추가될 때 자체적으로 세계표준시간(UTC)을 적용한다.

나의 입장에서는 데이터 -> 브라우저 출력 이다. 때문에 테이블에 저장된 값으로부터 하루가 밀려서 출력되는 것으로 느껴지지만

사용자 입장에서는 브라우저 동작 -> 데이터 저장 이다. 때문에 실제 사용자는 9일 밥 먹기 일정을 추가했지만 -9시간(한국 기준 UTC처리)가 되어 supabase에 저장이 되는 것이다.

(브라우저)4월 9일 00:00:00 로 선택 -> (supabase) 4월 8일 15:00:00 저장

연속 일정 처리 - 종료일 정각

따라서 사용자가 선택한 시간에 맞추어 달력에 잘 출력된다.

하지만 이는 단일 일정에만 적용이 되고, 연속 일정에는 조금 다른 처리를 해주어야 한다.

위의 test 일정은 모두 5일 일정이다. 하지만 test-15는 4일 일정으로 출력된다. 왜 그럴까??

결론부터 말하자면 종료일 시간이 정각이기 때문이다.

test-15 시작일

test-15 종료일

test-15의 일정 데이터이다.

일정 시작일을 보면 UTC가 적용되어 13일로 저장되어있지만 formatted 값은 14일 정각이다.

일정 종료일을 보면 UTC가 적용되어 17일로 저장되어있다. 마찬가지로 formatted 값을 보면 18일 정각이다.

시작일은 formatted 데이터가 정각이어도 시작하는 날이기에 정상적으로 표시되지만

종료일은 정각 시간이 적용되어 18일 이전까지만 달력에 표시된다.

따라서 종료일을 1시간 정도 늘려 적용시키면(일정 입력 기능 담당 팀원 분이 적용)

종료일이 18일 오전 1시로 설정되어 위의 달력처럼(test-16) 잘 출력된다.

[사람별_Day5] RBC 파헤치기 4 - 기존 스타일과 커스터마이징

채._. — Thu, 3 Apr 2025 22:38:04 +0900

RBC의 렌더링 방법(CRS)까지 파악하여 캘린더 형태를 출력하였다!

RBC의 기본적인 스타일이며, 커스터마이징을 위한 내용들을 정리한다.

RBC의 기본 스타일

RBC npm 문서를 읽던 중 SASS에 대해 알게 되었다.

문서에는 다음과 같이 나와있다.

이 말인즉슨,

RBC의 기본 스타일이 적용된 CSS 파일(react-big-calendar.css)이 있고 이를 바로 import 하여 접근할 수 있다.
하지만 스타일을 커스터마이징하려면 SASS 파일을 수정해야 한다.
이렇게 수정한 SASS 파일은 새로운 CSS 파일을 빌드하며 직접 import 한다.

초기 세팅 중 아래와 같이 캘린더 컴포넌트에 인라인 스타일 요소를 적용시켰다.

공식 문서에 나와있듯 달력의 컨테이너 요소에 높이를 주어야 화면에 나타나기 때문이다.

이때 CSS 파일을 import를 했기 때문에 기본 스타일에 접근할 수 있었던 것이다!

import "react-big-calendar/lib/css/react-big-calendar.css";

	<Calendar
        localizer={localizer}
        events={events}
        startAccessor="start"
        endAccessor="end"
        style={{ height: 500 }} // ✅ 달력 높이(달력 나타내기 위함)
      />

높이를 주지 않으면 다음과 같이 출력된다.

RBC에서 기본적으로 제공하는 스타일 요소들

가장 기본 형태의 CSS 요소를 7개의 섹션으로 나누어 살펴보겠다.

1. 캘린더 전체 레이아웃 (.rbc-calendar)

display: flex;로 구성되어 있음
내부적으로 rbc-toolbar, rbc-month-view 등의 요소를 포함

.rbc-calendar {
  box-sizing: border-box;
  display: flex;
  flex-direction: column;
  height: 100%;
  font-family: sans-serif;
  font-size: 14px;
}

2. 툴바 스타일 (.rbc-toolbar)

월 변경 버튼과 현재 날짜 표시하는 부분
버튼 기본 스타일 적용됨

.rbc-toolbar {
  display: flex;
  align-items: center;
  justify-content: space-between;
  margin-bottom: 10px;
}

.rbc-toolbar button {
  background-color: #f7f7f7;
  border: 1px solid #ddd;
  padding: 5px 10px;
  cursor: pointer;
}

// 기본 버튼 스타일
.rbc-toolbar button:hover {
  background-color: #e6e6e6;
}

3. 요일 헤더 스타일 (.rbc-header)

요일 표시하는 부분 (예: "일", "월", "화", …)

.rbc-header {
  text-align: center;
  padding: 10px;
  background-color: #f7f7f7;
  border-bottom: 1px solid #ddd;
}

4. 날짜 셀 스타일 (.rbc-day-bg)

각 날짜 칸에 적용되는 스타일

.rbc-day-bg {
  border-right: 1px solid #ddd;
}

// 주말 스타일
.rbc-day-bg.rbc-off-range-bg {
  background-color: #f3f3f3;
}

5. 이벤트 스타일 (.rbc-event)

캘린더에 표시되는 일정(이벤트) 스타일

.rbc-event {
  background-color: #3174ad; /* 기본 파란색 */
  color: white;
  padding: 4px;
  border-radius: 4px;
}

// 마우스 오버 시 스타일
.rbc-event:hover {
  background-color: #265985;
}

// 연속 이벤트 스타일
.rbc-event-continues-before {
  border-top-left-radius: 0;
  border-bottom-left-radius: 0;
}
.rbc-event-continues-after {
  border-top-right-radius: 0;
  border-bottom-right-radius: 0;
}

6. 현재 날짜 강조 (.rbc-today)

오늘 날짜 배경색 강조

.rbc-today {
  background-color: rgba(0, 0, 255, 0.1);
}

7. 선택된 날짜 스타일 (.rbc-selected-cell)

드래그로 날짜 범위 선택 시 강조 표시됨

.rbc-selected-cell {
  background-color: rgba(0, 0, 255, 0.2);
}

기존 스타일을 덮어쓰지 않고 유지하는 방법

앞서 본 7가지의 기존 스타일을 유지하고, 그 이외의 부분에 새로운 스타일을 적용하고 싶다면?

1. 기존 스타일을 확장하는 방식

기존 스타일의 이름을 확장하여 새로운 스타일을 적용한다.

.rbc-calendar {
  background-color: white; // 기존 스타일 유지
}
.rbc-calendar.custom {
  border: 2px solid red;  // 추가적인 스타일만 적용
}

2. 기존 스타일 상속

@extend를 사용하여 기존의 스타일을 물려받아 새로운 스타일 이름을 지정한다.

.custom-calendar {
  @extend .rbc-calendar; 
  border: 2px solid red;
}

3. CSS 변수 활용

RBC의 기존 SCSS 변수를 변경하려면 $변수를 사용하지만 새로운 스타일을 추가할 때는 --변수로 선언하고 var(--변수)로 사용한다.

// styles.scss (기존 RBC 스타일 수정)
@import 'react-big-calendar/lib/sass/styles';

$event-background-color: red;  // 기존 이벤트 배경색 변경

.rbc-event {
  background-color: $event-background-color !important;
}



// styles.css (새로운 스타일 지정)
:root {
  --custom-event-bg: blue; // 새로운 CSS 변수
}

.my-custom-event {
  background-color: var(--custom-event-bg) !important;
}

RBC의 SASS

상단에 적은 것처럼 RBC의 스타일을 커스터마이징하려면 SASS 파일을 수정해야 한다.

그렇다면 SASS는 무엇이며 어떻게 작동하는 것일까?

SASS와 SCSS

RBC 내부적으로 커스터마이징을 위해서는 SASS 파일을 수정해야 한다.

커스터마이징 한 스타일을 브라우저에 적용하기 위해서는 CSS 파일이 필요하다.

브라우저는 직접 SCSS 파일을 이해하지 못한다.

즉, SCSS 파일을 브라우저에서 사용하기 위해서는 SCSS 파일을 CSS 파일로 컴파일하여 브라우저가 이해할 수 있는 CSS 파일로 변환해야 한다.

RBC와 브라우저의 간극을 해결해주는 것이 Sass 이다.

따라서 Sass라는 것은 CSS 전처리기 도구이며, RBC의 커스터마이징을 브라우저에 적용할 수 있도록 도와준다.

Sass(=SASS)는 CSS 전처리기 도구이다.
SCSS는 Sass에서 지원하는 문법 스타일 형식이다.
RBC 내부 스타일 파일은 SCSS(.scss) 형식으로 되어있다.

// Sass(.sass)
$primary-color: blue

body
  background: $primary-color

nav
  ul
    margin: 0
    padding: 0

// SCSS(.scss)
$primary-color: blue;

body {
  background: $primary-color;
}

nav {
  ul {
    margin: 0;
    padding: 0;
  }
}

참고 자료

CSS 적용 우선 순위

RBC가 갖고있는 기본 스타일과 커스터마이징을 위한 파일까지 알아보았다.

기존 스타일에 접근하지 않고 SASS 파일을 수정하였을 때, 기존 스타일과 겹치는 부분이 있다면 최종적으로 어떤 것이 반영될까?

인라인 스타일 (style={{}}) → 가장 강함
ID 선택자 (#calendar)
클래스 선택자 (.rbc-calendar) / 속성 선택자 ([type="text"])
태그 선택자 (div, span 등)
기본 브라우저 스타일 → 가장 약함

만약, 기존 CSS와 겹칠 경우 기존 스타일보다 강하게 적용하려면

더 강한 선택자 사용 (.my-calendar-class .rbc-event 등)
!important 추가
CSS 파일이 빌드 후 더 나중에 로드되도록 조정
- 커스텀 CSS를 기존 CSS 이후에 import하기

import 'react-big-calendar/lib/css/react-big-calendar.css'; 
import './my-custom-calendar.scss';  // 커스텀 스타일이 더 나중에 로드됨!

[사람별_Day4] RBC 파헤치기 3 - 캘린더는 왜 CSR?

채._. — Wed, 2 Apr 2025 22:05:34 +0900

리액트 빅 캘린더(RBC)를 구현하기 전, 캘린더는 사용자와의 상호작용이 많이 필요하기 때문에(이벤트 핸들러) 클라이언트 컴포넌트여야 한다고 생각했다.
실제로 "use client"를 명시하지 않으면 아래와 같은 오류가 발생했다.

CSR인 이유

오류가 발생했다는 것은 필히 클라이언트 컴포넌트여야 한다는 것인데..

그 이유가 무엇일까?

1. RBC는 내부적으로 클래스 컴포넌트를 사용

우선 사진과 같은 오류는 클래스 컴포넌트 기반 라이브러리를 서버 컴포넌트에서 렌더링하려고 할 때 발생한다.

클래스 컴포넌트는 서버 컴포넌트에서 동작할 수 있도록 설계되지 않았다.

따라서 RBC는 Next.js의 서버 컴포넌트 환경에서는 이를 직접 실행할 수 없다.

2. 이벤트 핸들링

일정 클릭, 드래그 등 사용자와의 상호작용이 필요한 이벤트들은 서버 컴포넌트에서 사용될 수 없다.

3. RBC는 DOM을 조작

캘린더 특성상 DOM 요소를 조작하기 때문에 document와 같은 브라우저 API는 서버 사이드에서 실행할 수 없다.

React-Big-Calendar의 DOM 조작

RBC는 React 기반의 라이브러리지만, 내부적으로 브라우저의 DOM을 직접 조작하는 기능을 포함하고 있다.

1. 이벤트 렌더링 및 스타일 적용

캘린더 화면을 직접 생성
월간/주간 뷰를 전환하면 기존 DOM을 지우고 새롭게 렌더링
스타일을 동적으로 적용(eventPropGetter)

2. 드래그 & 드롭

사용자의 클릭과 드래그를 통해 이동하거나 크기 조절
마우스 이벤트 감지, 위치 조작
DOM 이벤트를 직접 핸들링(내부 라이브러리:react-dnd)

3. 툴팁, 팝업, 모달

DOM에 새로운 요소 추가, 조작(내부 라이브러리:react-popper)

4. 반응형 및 동적 높이 조정

브라우저 크기에 따라 동적으로 높이 조정(style 속성을 활용:autoHeight)
window.resize 이벤트를 추가하여 DOM을 다시 그리는 반응형 구현

그렇다면 왜 DOM을 조작하는 것일까?

state로 관리하게 되면 필요한 부분만 리렌더링 되어서 사용자에게 변동사항을 더욱 빠르게 보여줄 수 있는 것 아닐까?

한마디로 정리하자면 캘린더의 복잡한 레이아웃과 성능 최적화를 위한 것이다.

state가 변화하면 리렌더링이 일어나게 된다.

이 동작을 자세히 뜯어보자면

페이지 전체 중, 일부만 변동이 일어난다. -> 원본인 DOM과 비교하여 변동된 부분(state)만 감지한다. -> 리렌더링을 통해 변동된 부분을 반영한다.

state로 관리하는 부분이 적거나 확실하다면 이런 방식이 훨씬 효율적이다.

하지만 RBC는

이벤트 하나가 바뀌어도 전체 캘린더 UI를 다시 렌더링 해야 한다.
즉각적으로 반응해야 하는 드래그&드롭은 실시간으로 부드러운 반영이 필요하다.
많은 기능이 있는 캘린더의 경우에는 예상보다 더 많은 요소가 다시 렌더링될 수도 있다.
캘린더와 관련이 없는 부분임에도 캘린더가 자식컴포넌트 입장이 된다면 리렌더링이 발생한다.

이와 같은 이유들 때문에 state로 관리하게 되면 리렌더링이 불필요하게 발생할 수 있다.

일정을 State로 관리

RBC가 DOM(Document Object Model) 조작을 한다면,

state를 어떻게 활용하는 거지? 아니, 사용할 수나 있나??

쉽게 생각하면 껍데기는 DOM으로 조작, 알맹이는 state로 관리하는 것이다.

일정과 관련된 데이터를 state로 관리하고, 이를 캘린더에 반영하는 방식을 사용한다.

위에서 살펴보았듯이 RBC는 events 배열을 기반으로 일정을 표시한다.

이 events를 state로 관리하여 동적으로 일정을 관리(추가, 이동, 삭제)하는 것이다.

useState의 초기값을 이벤트 배열로 두고, 일정이 변동되면 setState를 통해 캘린더 UI가 자동으로 업데이트 된다.

클릭 이벤트나 API 연동 등을 통해 일정을 동적으로 관리하는 것이다.

예제 코드: events를 useState로 관리하기

import { useState } from "react";
import { Calendar, dateFnsLocalizer } from "react-big-calendar";
import { format, parse, startOfWeek, getDay } from "date-fns";

const localizer = dateFnsLocalizer({
  format,
  parse,
  startOfWeek,
  getDay,
  locales: { "en-US": require("date-fns/locale/en-US") },
});


const MyCalendar = () => {
// ✅ `events`를 state로 관리
  const [events, setEvents] = useState([
    {
      title: "회의",
      start: new Date(2024, 3, 10, 10, 0), // 4월 10일 10:00 AM
      end: new Date(2024, 3, 10, 12, 0),   // 4월 10일 12:00 PM
    },
  ]);

  // ✅ 새로운 이벤트 추가 함수
  const addEvent = () => {
    const newEvent = {
      title: "새 일정",
      start: new Date(2024, 3, 15, 14, 0), // 4월 15일 2:00 PM
      end: new Date(2024, 3, 15, 16, 0),   // 4월 15일 4:00 PM
    };
    setEvents([...events, newEvent]); // 기존 이벤트에 새 이벤트 추가
  };

  return (
    <div>
      <button onClick={addEvent}>새 일정 추가</button> {/* 버튼 클릭 시 새로운 일정 추가 */}
      <Calendar
        localizer={localizer}
        events={events} // ✅ state로 관리되는 events 전달
        startAccessor="start"
        endAccessor="end"
        style={{ height: 500 }}
      />
    </div>
  );
};

export default MyCalendar;

[사람별_Day4] RBC 파헤치기 2 - date-fns

채._. — Wed, 2 Apr 2025 21:54:43 +0900

RBC npm 문서를 읽던 중, 날짜 형식을 지정해야 한다는 점을 알았다.

RBC는 기본적으로 날짜 및 시간을 처리하지 않기 때문에

형식을 지정하기 위해 네 가지의 플러그인을 지원하고 있다.

나만의 생각 정리
RBC는 달력 형태를 만들어 줄 뿐,
해당 숫자가 날짜를 뜻하는 바임을 알게 해주는 것은 플러그인의 역할이다.
즉, 캘린더와 사용자 사이에서 캘린더에게는 문자열로 전달, 사람에게는 날짜로 전달해 주는 통역가 역할이다.

RBC에서 지원하는 네 가지 플러그인을 비교해보았다.

공식문서:
Moment.js , Globalize.js , date-fns , Day.js

라이브러리	번들 크기	성능	Tree Shaking 지원	TypeScript 지원	타임존 지원
Moment.js	약 260KB	느림	X	O	(moment-timezone 필요)
Globalize.js	약 200KB	느림	X	X	(Intl 지원)
date-fns	약 20KB	빠름	O	O	X
Day.js	약 2KB	매우 빠름	O	O	(플러그인 필요)

나는 가벼운 번들 크기, 빠른 속도, 쉬운 접근성을 기준으로 두어 고려했다.

그에 적합하는 것은 date-fns로, 문서도 잘 정리되어 있는 듯 하다.

기준에 따르자면 Day.js가 가장 적합하지만,

타임존 지원에 대해 팀원들과 이야기를 나눈 결과 한국인 사용자만 고려하여 진행하기로 했다.

또한 샤드시엔에서 Day Picker를 사용하는 팀원분도 date-fns를 사용해야 했기에 최종 결정은 date-fns !

date-fns 사용하여 캘린더 나타내기

date-fns 설치

pnpm install date-fns

TypeScript 설치

date-fns가 기본적으로 TS를 포함하지만,
모듈 'react-big-calendar'에 대한 선언 파일을 찾을 수 없습니다. 오류로 인해 설치했다.
- react-big-calendar 패키지가 TypeScript용 타입 정의 파일을 제공하지 않기 때문에 발생한 오류이다.
- TypeScript는 .d.ts(타입 선언 파일)가 없는 경우, 해당 패키지를 알 수 없다고 판단한다.

설치 후 import

"use client";
import { Calendar, dateFnsLocalizer } from "react-big-calendar";
import { format, parse, startOfWeek, getDay } from "date-fns";
import { enUS } from "date-fns/locale/en-US";
import { ko } from "date-fns/locale/ko";

// 아래의 import는 해당 컴포넌트를 포함하는 페이지에 입력함
import "react-big-calendar/lib/css/react-big-calendar.css";

지역화 설정

// 로케일(지역화) 설정
const locales = {
  "en-US": enUS, //미국-영어 : 미국식 날짜
  "ko-KR": ko, //한국-한글 : 한국식 날짜
};

dateFnsLocalizer로 RBC와 연결

const localizer = dateFnsLocalizer({
  format, // 날짜를 문자열로 변환
  parse, // 문자열을 날짜 객체로 변환
  startOfWeek, // 한 주의 시작 요일 설정
  getDay, // 날짜의 요일 가져오기
  locales, // 다국어 설정 적용
});

RBC의 <Calendar /> 컴포넌트 props 설정

const MainCalendar = () => {
  return (
    <div>
      <Calendar
        localizer={localizer} // 날짜 및 시간 포맷을 지정(dateFnsLocalizer)
        events={[]} // 여기에 이벤트 추가 가능
        startAccessor="start" // 각 이벤트 객체에서 시작 시간
        endAccessor="end" // 종료 시간
        style={{ height: 500 }} // 캘린더의 높이(CSS 직접 지정)
      />
    </div>
  );
};

props 중 events 상세 설명

events 배열의 각 객체는 title, start, end을 가짐
따라서 startAccessor="start"와 endAccessor="end"는 그 속성을 가져옴
new Date의 인자가 3인데 왜 4월일까?
- new Date(year, month, day, hour, minute, second)
- JS new Date()의 월 인덱스는 0부터 시작하는 제로 인덱스
  1월 = 0 / 2월 = 1 / 3월 = 2 / ... / 12월 = 11

// 일정 예시
const events = [
  {
    title: "회의",
    start: new Date(2024, 3, 10, 10, 0), // 4월 10일 10:00 AM
    end: new Date(2024, 3, 10, 12, 0),   // 4월 10일 12:00 PM
  },
];

전체 로직

// src > components > Calendar.tsx

"use client";
import { Calendar, dateFnsLocalizer } from "react-big-calendar";
import { format, parse, startOfWeek, getDay } from "date-fns";
import { enUS } from "date-fns/locale/en-US";
import { ko } from "date-fns/locale/ko";


const locales = {
  "en-US": enUS,
  "ko-KR": ko, 
};

const localizer = dateFnsLocalizer({
  format,
  parse,
  startOfWeek,
  getDay,
  locales,
});

const MainCalendar = () => {
  return (
    <div>
      <Calendar
        localizer={localizer}
        events={[]}
        startAccessor="start"
        endAccessor="end"
        style={{ height: 500 }}
      />
    </div>
  );
};

export default MainCalendar;

[사람별_Day4] RBC 파헤치기 1 - Webpack의 CSS 처리

채._. — Wed, 2 Apr 2025 16:12:40 +0900

리액트 빅 캘린더(RBC)를 프로젝트에 적용하기 전, 파악 겸 연습으로 개인 파일을 생성했다.

초기 세팅부터 난관이 시작되는데...

협업 시 적용하기 위해 기록해본다.

진행 상황

리액트 빅 캘린더 설치
pnpm dev
오류 : You forgot to add 'mini-css-extract-plugin' plugin

'please read' 링크로 들어가보니 'CSS 코드가 포함된 JS 파일 별로 CSS 파일을 생성' 무슨 말??
- Webpack은 모든 코드(JS, CSS 등)를 번들링해서 하나의 JavaScript 파일로 만듬
- 하지만 이렇게 하면 CSS가 JS 번들에 포함되어 브라우저에서 로딩할 때 최적화되지 않을 수 있음

mini-css-extrant-plugin 적용

[리액트 환경]

아래는 리액트 환경에서 mini-css-extrant-plugin을 적용하는 방법이다.

작동 방식

CSS 코드 추출: Webpack이 JS 파일을 처리할 때 import "./style.css" 같은 코드가 있으면
원래는 이 CSS가 JS 내부에 포함되지만, mini-css-extract-plugin을 사용하면 CSS를 별도의 .css 파일로 분리
CSS 파일 생성: 번들링이 완료되면 JS 번들과 별개로 .css 파일이 생성됨
CSS 로드 최적화: 이렇게 하면 브라우저가 CSS를 별도로 로드할 수 있어 JS + CSS를 한 번에 로드하는 것보다 더 효율적

적용 방법 (React 프로젝트에서 적용)

설치

npm install mini-css-extract-plugin --save-dev

Webpack 설정 변경 (webpack.config.js)

const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
  plugins: [new MiniCssExtractPlugin()], // 플러그인 추가
};

react-big-calendar에서 왜 필요할까?

react-big-calendar는 내부적으로 CSS를 사용한다.

하지만 Webpack이 CSS를 처리할 때, mini-css-extract-plugin이 없으면 CSS가 JS 번들 내부에 포함되려고 해서 충돌이 발생한다.

따라서 해당 플러그인을 추가하면 RBC 내부 CSS를 별도의 .css 파일로 생성하게 되고, JS 번들과 분리되어 캘린더만의 CSS가 적용된다.

그로 인한 효과는

1. 번들 크기 최적화

JS 로딩과 CSS 로딩이 동시에 진행할 수 있어 성능이 좋아진다.
JS 로드 이후에 CSS 적용이 아닌, 스타일이 먼저 로드될 수 있음.

JS가 로드되기도 전에 스타일이 먼저 로드되면 CSS가 적용 안 되는 거 아니야?

오히려 더 빠르게 보이게 된다!

JS에 CSS가 포함되어 있을 때는 'JS 로드 -> CSS 적용' 순서이기 때문에

스타일이 적용되지 않은 HTML 요소가 먼저 보이며, 깜빡이는 현상이 발생할 수 있다.

반면 스타일이 먼저 적용되면 지연 없이 화면 구성이 이루어진다.

2. 캐싱 최적화

스타일이 변경되지 않는 한 CSS는 브라우저에서 캐싱되고, JS 파일만 새로 받도록 할 수 있다.

3. 스타일 충돌 방지

RBC 내부에서 사용하는 CSS와 프로젝트에서 직접 정의한 CSS가 충돌할 가능성이 있는데,
RBC의 CSS를 독립적으로 유지 가능하다.

[Next.js 환경]

반면 나와 같이 Next.js로 프로젝트를 진행하는 경우에는 한 줄만 추가하면 된다.

import "react-big-calendar/lib/css/react-big-calendar.css";

왜냐하면 Next.js는 Webpack 설정을 자동 관리하고 CSS 로더가 기본으로 포함되어 있기 때문

Next.js는 next.config.js 내부에서 Webpack을 자동으로 설정하기 때문에, 기본적인 CSS 처리는 추가 설정 없이 동작한다.
Next.js는 .css 파일을 import하는 것을 지원하므로, mini-css-extract-plugin을 직접 설정할 필요 없다.

그렇다면 import를 어디서 하느냐??

보통 여러 페이지에서 캘린더 CSS를 적용해야 하는 경우, RootLayout에 적용하여 전역 스타일로 지정한다.

하지만 이번 프로젝트의 경우 '캘린더 페이지'에서만 리액트 빅 캘린더를 사용한다.

만약, 이런 경우에 RootLayout에 import를 하게 된다면?

캘린더를 사용하지 않는 페이지의 CSS와 충돌 가능성이 있다.

따라서 캘린더 컴포넌트가 포함된 해당 페이지에 import를 해주면 된다.

정상 작동 확인!