v5.3으로 마이그레이션
v5.3으로 마이그레이션 (Migrating to v5.3)
Bootstrap 5.3으로 업그레이드할 때 알아 두어야 할 변경 사항과 deprecated 항목들을 정리해요.
출처: 문서
본문
v5.3.0은 Bootstrap 5.X 버전 계열의 주요 업데이트로, 색상 모드(color mode)/다크 모드 지원, CSS 커스텀 프로퍼티 확장, 유틸리티 API 개선 등이 포함돼요.
v5.3.0 강조 기능 (Highlights)
- 색상 모드(Color modes):
data-bs-theme속성으로 라이트 모드와 다크 모드를 비롯한 테마를 요소별로 적용할 수 있어요. 기존에는 다크 모드를 위해 별도의 CSS를 수동으로 관리해야 했지만, 이제 Bootstrap에서 기본 제공해요. - CSS 변수 확장: 모든 Sass 변수가 CSS 커스텀 프로퍼티(CSS 변수)로 노출돼요. 컴파일 없이도 런타임에 일부 스타일을 변경할 수 있어요.
- 테마 색상 확장:
$theme-colors와 관련 변수들에-bg-subtle,-border-subtle,-text-emphasis같은 접미사를 가진 색상 변형 클래스가 추가됐어요.
Dependencies
- Bootstrap을 사용하려면
@popperjs/core와 Sass가 여전히 필요해요. - Node.js 버전과 빌드 도구 관련 요구 사항이 업데이트됐을 수 있으니 문서의 빌드/설치 가이드를 확인하세요.
Sass
- 커스텀 CSS 변수를 생성하는 방식이 더 포괄적으로 바뀌었어요.
--bs-*접두어를 가진 커스텀 프로퍼티가 더 많은 컴포넌트에 추가됐어요. - 색상 모드를 지원하기 위해
_variables-dark.scss같은 다크 모드용 변수 파일과 관련 함수·mix들이 도입됐어요. - deprecated된 일부 Sass 변수/함수가 정리됐어요. 커스텀 테마를 만드는 경우 자신의 변수 재정의가 새 기본값과 충돌하는지 확인하세요.
Utilities
- 유틸리티 API를 통해 생성되는 유틸리티 수가 늘었어요. 특히 배경, 테두리, 텍스트 색상의
-subtle/-emphasis변형이 추가됐어요. text-opacity,bg-opacity,border-opacity유틸리티가 CSS 변수 기반으로 동작해요.
Theming & class deprecated
다음과 같은 클래스·유틸리티가 deprecated되었어요:
.text-muted—.text-body-secondary로 대체 (v6.0.0에서 제거 예정).text-black-50과.text-white-50—.text-opacity-*유틸리티로 대체 (v6.0.0에서 제거 예정)
이름이 바뀌거나 제거된 클래스를 사용 중이라면, 새 클래스 이름으로 마이그레이션해야 해요.
Upgrading from earlier versions
v4.x에서 오는 경우에는 v4 → v5 마이그레이션 가이드를 먼저 확인하고, v5.0~5.2에서 오는 경우에는 각 릴리스 노트를 확인하며 변경 사항을 반영하세요. 마이그레이션 시에는 컴포넌트별 문서와 예제를 교차 확인하는 것이 좋아요.