bootstrap-v4-v6-migration

Bootstrap v4 から v6 への移行

v4 から v6 へ直接移行する方法はありません。2 段階で移行します。まず v4 から v5 へ（このスキル）、次に v5 から v6 へ（bootstrap-v5-v6-migration スキル）移行します。中間の段階を省略すると、うまくいきません。v4 の名前の多くは v5 で変更され、さらに v6 でも再度変更されているためです。.text-primary は v5 を経て初めて .fg-primary になり、.badge-primary は .badge.bg-primary を経て .badge.theme-primary になります。

ワークフロー

各ステップを順番に進めます。次に進む前に、各ステップの後でコードベースを検索し、v4 のパターンが残っていないことを確認してください。

• ステップ 1：2 段階の移行を計画する
• ステップ 2：v4 から v5 — 依存関係、ビルド、Sass
• ステップ 3：v4 から v5 — JavaScript
• ステップ 4：v4 から v5 — クラスと属性
• ステップ 5：v5 から v6 — v6 移行スキルに引き継ぐ
• ステップ 6：検証する

---

ステップ 1：2 段階の移行を計画する

1. v6 に手を付ける前に、プロジェクトを Bootstrap 5 に移行して動作する状態にします。ビルドが成功し、ページが表示され、テストがすべて成功している状態にしてください。v5 段階を独立したコミット（または PR）として取り込むことで、問題が起きたときに 2 回の名前変更を切り分けやすくなります。
2. まず、移行対象を洗い出します。最も時間がかかる v4 の機能は、カスタムフォーム、.input-group-append／.input-group-prepend、ジャンボトロン、.media オブジェクト、.card-deck／.card-columns、Bootstrap プラグインを呼び出す jQuery です。
3. jQuery の扱いは別途判断してください。Bootstrap 5 では jQuery が削除されていますが、アプリでほかの用途に使っている可能性があります。Bootstrap の依存関係から jQuery を外しても、jQuery 自体を削除する必要はありません。
4. ブラウザーの最低要件を確認します。Bootstrap 5 では IE がサポート対象外になります。Bootstrap 6 では、macOS および iOS 上の Chrome と Edge 130、Firefox 132、Safari 18 が必要です。

---

ステップ 2：v4 から v5 — 依存関係、ビルド、Sass

1. 依存関係を更新し、jQuery／Popper v1 の組み合わせを削除します。

   npm i --save bootstrap@5 @popperjs/core
   npm uninstall popper.js
   

   popper.js（v1）は @popperjs/core（v2）に置き換わります。Bootstrap 5 のバンドルには Popper が含まれますが、スタンドアロンの bootstrap.js には含まれません。

2. Sass コンパイラーを Dart Sass（npm i --save-dev sass）に切り替えます。Node Sass／LibSass はサポートされていません。現時点では @import を使い続けてください。v5 では引き続き使用されます。@use への移行は v6 段階で行います。

3. Sass マップは自動的にマージされなくなりました。v4 では $theme-colors にキーを 1 つ追加するだけで十分でしたが、v5 では、残すキーを含むマップ全体を定義する必要があります。

4. 名前が変更された関数とミックスインを更新します。

   v4	v5
   color-yiq()	color-contrast()
   theme-color()、gray()	削除 — $theme-colors／$grays を直接参照
   theme-color-level()	tint-color()／shade-color()
   lighten()／darken()	tint-color()／shade-color()
   media-breakpoint-down(md)	media-breakpoint-down(lg) — 次に小さいブレークポイントではなく、ブレークポイント自体を指定します
   media-breakpoint-between(sm, md)	media-breakpoint-between(sm, lg) — 上限も同様にずれます

   ブレークポイントのパラメーター変更は明示されません。エラーは発生せず、メディアクエリが 1 つずれたブレークポイントに適用されるだけです。すべての呼び出しを監査してください。

5. 印刷スタイル、$enable-* フラグ、ユーティリティ API は v5 でいずれも形式が変わりました。v4 のミックスインでカスタムユーティリティを生成していた場合は、v5 の $utilities マップを使って書き直してください。

---

ステップ 3：v4 から v5 — JavaScript

1. すべてのデータ属性に bs を付けます。これは機械的な変更ですが、影響範囲は広範です。

   v4	v5
   data-toggle	data-bs-toggle
   data-target	data-bs-target
   data-dismiss	data-bs-dismiss
   data-parent	data-bs-parent
   data-ride	data-bs-ride
   data-slide, data-slide-to	data-bs-slide, data-bs-slide-to
   data-spy	data-bs-spy
   data-backdrop, data-keyboard	data-bs-backdrop, data-bs-keyboard
   data-content, data-placement, data-trigger	data-bs-content, data-bs-placement, data-bs-trigger

   属性として渡すオプションにも、同じルールが適用されます。data-<option> は data-bs-<option> になります。

2. jQuery プラグインの呼び出しを、コンストラクターまたは静的ゲッターに置き換えます。

   // v4
   $('#myModal').modal('show')
   $('#myTooltip').tooltip()
   
   // v5
   const modal = new bootstrap.Modal(document.querySelector('#myModal'))
   modal.show()
   
   bootstrap.Tooltip.getOrCreateInstance(document.querySelector('#myTooltip'))
   

3. jQuery のイベントハンドラーを、ネイティブリスナーに置き換えます。Bootstrap 5 はネイティブの CustomEvent をディスパッチするため、$(el).on('shown.bs.modal', …) は機能しなくなります。

   // v5
   document.querySelector('#myModal').addEventListener('shown.bs.modal', event => {
     // event.relatedTarget replaces event.relatedTarget from the jQuery event
   })
   

4. 小規模な API の名称変更：

   • _getInstance() → getInstance()。新しい getOrCreateInstance() の使用を推奨します。
   • サニタイザーオプションの whiteList → allowList。
   • Tooltip と Popover の title／content は引き続き関数を受け付けますが、this は jQuery 要素ではなくなります。

5. jQuery の noConflict や $.fn.button('toggle') のような呼び出しに依存していた場合は、クラス API を使うよう書き換えてください。互換レイヤーで補える jQuery インターフェースは残っていません。

---

ステップ 4：v4 から v5 — クラスと属性

方向を示すユーティリティが論理方向に（RTL サポート）

v4	v5
.ml-*、.mr-*	.ms-*、.me-*
.pl-*、.pr-*	.ps-*、.pe-*
.float-left、.float-right	.float-start、.float-end
.text-left、.text-right	.text-start、.text-end
.border-left、.border-right	.border-start、.border-end
.rounded-left、.rounded-right	.rounded-start、.rounded-end
.dropleft、.dropright	.dropstart、.dropend

レスポンシブ版にも同じ名称変更が適用されます（.ml-md-3 → .ms-md-3）。

タイポグラフィとヘルパー

v4	v5
.font-weight-bold、-normal、-light、-bolder、-lighter	.fw-bold、.fw-normal、.fw-light、.fw-bolder、.fw-lighter
.font-italic	.fst-italic
.text-monospace	.font-monospace
.sr-only、.sr-only-focusable	.visually-hidden、.visually-hidden-focusable
.embed-responsive、.embed-responsive-16by9	.ratio、.ratio-16x9
.text-justify、.text-hide、.pre-scrollable	削除
.rounded-sm、.rounded-lg	.rounded-1、.rounded-3

フォーム

v4 から v5 への書き換えで最も規模が大きい変更です。カスタムフォームコントロールは標準クラスに統合されました。

v4	v5
.custom-select	.form-select
.custom-range	.form-range
.custom-file、.form-control-file	.form-control（<input type="file"> に指定）
.form-control-range	.form-range
.custom-control.custom-checkbox	.form-check
.custom-control.custom-radio	.form-check
.custom-control.custom-switch	.form-check.form-switch
.custom-control-input	.form-check-input
.custom-control-label	.form-check-label
.custom-control-inline	.form-check-inline
.form-group	.mb-3 などのスペーシングユーティリティ
.form-row	.row とガターユーティリティ（.g-*）
.form-inline	グリッドまたはフレックスユーティリティ（.row .row-cols-lg-auto、.d-flex）
クラスのない <label>	<label class="form-label">

入力グループからラッパーがなくなります。.input-group-append と .input-group-prepend を削除し、.input-group-text、ボタン、コントロールを .input-group の直接の子要素として配置してください。バリデーションフィードバックも、削除されたラッパーの外に移動します。

削除または再構成されたコンポーネント

v4	v5
.jumbotron	削除 — .bg-*、.p-*、.rounded-* を組み合わせてください
.media	削除 — .d-flex と gap／margin ユーティリティを使用してください
.card-deck、.card-columns	削除 — グリッド、または Masonry レイアウトには CSS columns を使用してください
.close	.btn-close（子要素の × を削除してください。アイコンは背景画像です）
.badge-primary など	.badge と .bg-primary を組み合わせます
.badge-pill	.rounded-pill
.btn-block	.d-grid のラッパー（ボタンを縦に並べる場合は .gap-* を追加します）
.thead-light、.thead-dark	<thead> に .table-light、.table-dark を指定します
.arrow（tooltip／popover）	.tooltip-arrow、.popover-arrow
.carousel-item-left、-right	.carousel-item-start、-end

バッジのリンクスタイルも削除されました。<a class="badge"> に hover／focus 状態が適用されなくなっています。

グリッド、ナビバー、ナビ

• .no-gutters → .g-0。ガターは .g-*、.gx-*、.gy-* ユーティリティで制御するようになりました。
• 新しい xxl ブレークポイント（1400px）が追加されました。既存の xl クラスの意味は変わりません。
• ナビバーでは、.navbar 内にコンテナーが必要になりました（<nav class="navbar"><div class="container">…）。
• タブとピルでは、.active を .nav-item から .nav-link に移します。.nav-item はラッパーとして省略できます。
• .dropdown-menu の項目には <button> または <a> を使用できます。プレーンテキスト用に .dropdown-item-text が追加されました。

---

ステップ 5：v5 から v6 へ — v6 移行スキルに引き継ぐ

プロジェクトが Bootstrap 5 でビルドされ、表示されるようになったら、bootstrap-v5-v6-migration スキルに切り替えて、その手順に沿って作業してください。v4 のパターンが残っている間は、これらの名前変更を行わないでください。スキルの検索・置換手順は v5 の名前を前提としています。

この段階では、次のような項目を扱います。

• @import から @use への変更、および Sass のスカラー値から CSS トークンマップへの移行（v6 では defaults() がテーママップを再びマージします）
• Popper から Floating UI への移行、および Datepicker 用の Vanilla Calendar Pro。バンドル版ビルドには両方のピア依存関係が含まれ、スタンドアロン版ビルドでは外部依存のままになります。
• -md- の挿入形式に代わる md: レスポンシブ接頭辞の構文
• Modal から Dialog、Offcanvas から Drawer、Dropdown から Menu への変更。Dialog と Drawer ではネイティブの <dialog> 要素を使用します。
• .btn-primary から .btn-solid .theme-primary への変更、および .text-* から .fg-* への変更
• window.bootstrap グローバルを持たない ESM 専用 JavaScript
• レスポンシブスタック、CSS Grid、ナビバー、リストグループ、カードグループ、スタックテーブル用のコンテナークエリコンテキスト

開始前に確認しておきたい v4 時代の詳細が 2 つあります。ステップ 4 で作成した .close → .btn-close 要素は v6 でもその名前のままですが、子の SVG を含めず、空のままにする必要があります。また、先ほど記述した .form-check マークアップは、v6 の .check／.radio／.switch 構造へ再度組み直します。

---

ステップ 6：検証

1. プロジェクトをビルドし、レンダリング結果を確認する前にコンパイルエラーを修正します。
2. v4 の古いパターンが残っていないか検索します。
   • data-toggle=, data-target=, data-dismiss=, data-ride=, data-slide, data-spy=（すべて data-bs-* になっているはずです）
   • class="close"、閉じるボタン内の ×（.btn-close になっているはずです）
   • badge-, badge-pill（.badge .bg-*／.rounded-pill になっているはずです）
   • custom-select, custom-control, custom-switch, custom-range, custom-file
   • form-group, form-row, form-inline, input-group-append, input-group-prepend
   • \bm[lr]-, \bp[lr]-, float-left, float-right, text-left, text-right, border-left, border-right
   • font-weight-, font-italic, text-monospace
   • no-gutters, sr-only, embed-responsive, jumbotron, media-body, card-deck, card-columns, btn-block, thead-light, thead-dark, pre-scrollable, text-justify
   • Bootstrap プラグイン名（.modal(、.tooltip(、.collapse(）の近くにある \$(、jQuery(
   • theme-color(, color-yiq(, theme-color-level(, media-breakpoint-down(
3. すべてのインタラクティブコンポーネントをクリックして動作を確認します。データ属性名の変更はエラーを出さずに失敗するため、data-toggle の見落としはエラーではなく、ボタンが反応しない状態として現れます。
4. フォームは特に念入りに確認します。カスタムコントロール、入力グループ、検証フィードバックはすべて構造が変わっています。
5. その後、ステップ 5 に進み、v6 の段階でも同じ手順を繰り返します。