[Trouble Shooting] AG-Grid v33 마이그레이션: Deprecated 속성 제거

문제 상황

프로젝트에서 사용 중이던 AG-Grid를 v33으로 업그레이드했더니 다음과 같은 문제들이 발생함:

1. 테마 충돌 오류: AG Grid: error #239 Theming API and CSS File Themes are both used in the same page
2. rowSelection deprecated 경고: using rowSelection with the values "single" or "multiple" has been deprecated
3. suppressRowClickSelection deprecated 경고: suppressRowClickSelection is deprecated

기존 코드가 모두 deprecated 방식으로 작성되어 있어 마이그레이션이 필요했음.

---

문제 1: 테마 충돌 (Error #239)

오류 메시지

AG Grid: error #239 Theming API and CSS File Themes are both used in the same page

원인

AG-Grid v33부터는 Theming API를 기본으로 사용하는데, 기존 CSS 파일(ag-grid.css, ag-theme-alpine.css)을 함께 import하면 충돌이 발생함.

해결 방법

Before (v32 이하)

// main.tsx
import 'ag-grid-community/styles/ag-grid.css';
import 'ag-grid-community/styles/ag-theme-alpine.css';

After (v33+)

// main.tsx
import './styles/ag-grid-custom.css';  // 커스텀 스타일만 사용

CSS 파일 import를 제거하고 커스텀 스타일만 사용하도록 변경함.

---

문제 2: rowSelection Deprecated

경고 메시지

As of version 32.2.1, using rowSelection with the values "single" or "multiple" has been deprecated

원인

AG-Grid v32.2+부터 rowSelection 속성이 문자열 방식에서 객체 방식으로 변경됨.

해결 방법

Before (Deprecated)

// gridDefaults.ts
export const DEFAULT_GRID_OPTIONS: GridOptions = {
  rowSelection: 'multiple',
  suppressRowClickSelection: true,
};

After (v32.2+)

// gridDefaults.ts
export const DEFAULT_GRID_OPTIONS: GridOptions = {
  rowSelection: {
    mode: 'multiRow',              // 'multiRow' | 'singleRow'
    enableClickSelection: false,   // suppressRowClickSelection 대체
  },
};

Migration 가이드

기존 방식	새 방식
rowSelection: 'multiple'	rowSelection: { mode: 'multiRow' }
rowSelection: 'single'	rowSelection: { mode: 'singleRow' }
suppressRowClickSelection: true	rowSelection.enableClickSelection: false

---

문제 3: suppressRowClickSelection Deprecated

경고 메시지

As of v32.2, suppressRowClickSelection is deprecated. Use rowSelection.enableClickSelection instead

원인

suppressRowClickSelection 속성이 rowSelection 객체의 enableClickSelection으로 통합됨.

해결 방법

위의 문제 2 해결 방법과 동일함. rowSelection 객체 내부에 enableClickSelection 속성으로 통합됨.

// Before
suppressRowClickSelection: true

// After
rowSelection: {
  enableClickSelection: false  // true/false 반전에 주의
}

주의: 기존 suppressRowClickSelection은 “억제(suppress)”하는 의미였지만, 새 속성은 “활성화(enable)”하는 의미이므로 boolean 값이 반전됨.

---

결과

마이그레이션 후 모든 경고와 오류가 사라졌으며, AG-Grid가 정상적으로 동작함.

최종 설정 파일

// src/config/gridDefaults.ts
import type { ColDef, GridOptions } from 'ag-grid-community';

export const DEFAULT_COL_DEF: ColDef = {
  sortable: true,
  filter: true,
  resizable: true,
  minWidth: 100,
};

export const DEFAULT_GRID_OPTIONS: GridOptions = {
  defaultColDef: DEFAULT_COL_DEF,
  pagination: true,
  paginationPageSize: 20,
  paginationPageSizeSelector: [10, 20, 50, 100],

  // v32.2+ 새 형식
  rowSelection: {
    mode: 'multiRow',
    enableClickSelection: false,
  },

  animateRows: true,
  enableCellTextSelection: true,
  suppressCellFocus: true,
  rowHeight: 52,
  headerHeight: 52,
};

---

주의할 점

1. Theming API와 CSS 파일 혼용 금지

• v33+에서는 CSS 파일을 import하지 말 것.
• 커스텀 스타일이 필요한 경우 별도 CSS 파일을 생성해서 사용.

2. Boolean 값 반전 확인

• suppressRowClickSelection: true → enableClickSelection: false
• 의미가 정반대이므로 값을 반드시 확인할 것.

3. 모든 GridOptions 설정 확인

• 프로젝트 전체에서 rowSelection을 사용하는 모든 곳을 찾아 수정해야 함.
• IDE의 전역 검색 기능을 활용하면 편리함.

4. Legacy 모드 비활성화

• theme: "legacy" 옵션을 사용하면 기존 방식을 계속 사용할 수 있지만 권장하지 않음.
• 장기적으로 Theming API로 마이그레이션하는 것이 좋음.

---

AG-Grid v33 마이그레이션은 deprecated 속성들을 새 방식으로 변경하는 과정이었음. 특히 rowSelection 객체 형식과 Theming API 변경이 핵심이었음.

도움이 되셨길 바랍니다! 😀