js_cookie モジュールで Drupal の jQuery Cookie / core/js-cookie ライブラリを書き直す方法

移行経路の概観

1)Drupal 8 → 9:jQuery Cookie → core/js-cookie

歴史的背景:Drupal 9 は jQuery Cookie を js-cookie に置き換え、コードとライブラリのマッピング例を提供しました。https://www.drupal.org/node/3104677

# 以前(Drupal 8 / 初期の 9)
my_library:
  js:
    js/my_library.js: {}
  dependencies:
    - core/jquery
    - core/jquery.cookie
    - core/drupal

// 以前(jQuery Cookie の API)
(($, Drupal) => {
  Drupal.behaviors.myModule = {
    attach: () => {
      $.cookie('cutest', 'red panda');
      const myCookieValue = $.cookie('cutest');
      $.removeCookie('cutest');

      $.cookie.json = true;
      $.cookie('cutest', { animal: 'red panda' });
    },
  };
})(jQuery, Drupal);

その後(Drupal 9)は core/js-cookie に依存し、Cookies.* API を使いました: https://www.drupal.org/node/3104677

# その後(Drupal 9)
my_library:
  js:
    js/my_library.js: {}
  dependencies:
    - core/drupal
    - core/js-cookie

// その後(Drupal 9、js-cookie の API)
((Drupal, Cookies) => {
  Drupal.behaviors.myModule = {
    attach: () => {
      Cookies.set('cutest', 'red panda');
      const myCookieValue = Cookies.get('cutest');
      Cookies.remove('cutest');

      Cookies.set('cutest', JSON.stringify({ animal: 'red panda' }));
      const cutest = JSON.parse(Cookies.get('cutest') || 'null');
    },
  };
})(Drupal, window.Cookies);

2)Drupal 10.1 以降と 11:core/js-cookie → コントリビュートの js_cookie

Drupal コアは 10.1 で core/js-cookie を非推奨にし、11 で削除したため、コントリビュートの JS Cookie モジュールのライブラリ js_cookie/js-cookie に置き換える必要があります。https://www.drupal.org/node/3322720

Composer

composer require drupal/js_cookie

これにより、アップストリームの js-cookie パッケージ向けの Drupal アセットライブラリを公開するモジュールがインストールされます。https://www.drupal.org/project/js_cookie

モジュール/テーマの依存関係を宣言する(コントリビュート/カスタムプロジェクト向け)

# my_module.info.yml(またはテーマの .info.yml)
name: My Module
type: module
core_version_requirement: ^10 || ^11
dependencies:
  - js_cookie:js_cookie

プロジェクトページは、コントリビュートモジュール向けに js_cookie:js_cookie を依存関係として追加すること(そしてモジュールが独自の composer.json を持つ場合は composer で drupal/js_cookie を require すること)を明示しています。[4](https://www.drupal.org/project/js_cookie)

アセットライブラリの依存関係を切り替える

# これを置き換える(10.1 で非推奨、11 で削除)
# - core/js-cookie

# これに(コントリビュートモジュールが提供)
my_library:
  js:
    js/my_library.js: {}
  dependencies:
    - core/drupal
    - js_cookie/js-cookie

このとおりの置き換えが、非推奨化を告知したコアの変更記録で推奨されている経路です。[2](https://www.drupal.org/node/3322720)

JavaScript コード

すでに js-cookie の Cookies API を使っていたなら、JS コードに変更は必要ありません — 変わるのはライブラリの依存関係だけです。[2](https://www.drupal.org/node/3322720)

((Drupal, Cookies) => {
  Drupal.behaviors.myModule = {
    attach: () => {
      // Cookie を設定する。
      Cookies.set('cutest', 'red panda', { path: '/', sameSite: 'Lax' });

      // Cookie を取得する。
      const myCookieValue = Cookies.get('cutest');

      // Cookie を削除する。
      Cookies.remove('cutest', { path: '/' });

      // JSON を安全に保存/取得する。
      Cookies.set('cutest', JSON.stringify({ animal: 'red panda' }));
      const cutestRaw = Cookies.get('cutest');
      const cutest = cutestRaw ? JSON.parse(cutestRaw) : null;
    },
  };
})(Drupal, window.Cookies);

ヒント:js-cookie は RFC 6265 準拠で、古い jQuery Cookie とは、特に JSON について値のエンコード方法が異なります。Drupal 9 の変更記録がこれらの挙動の違いをまとめています。https://www.drupal.org/node/3104677

エコシステムからの例

• EU Cookie Compliance モジュールは core/js-cookie の非推奨化を追跡し、js_cookie/js-cookie への切り替えのパッチが提案されました。https://www.drupal.org/project/eu_cookie_compliance/issues/3380490
• さまざまなコントリビュートプロジェクトが、jQuery Cookie を js-cookie に置き換えるための、そして後に core/js-cookie の非推奨化に対処するための issue を提出しました。https://www.drupal.org/project/quicktabs/issues/3298649
  https://www.drupal.org/project/fpa/issues/3505122

ステップバイステップのアップグレード手順

A)jQuery Cookie から直接 js_cookie/js-cookie へ(Drupal 10 以降)

1. .libraries.yml から core/jquery と core/jquery.cookie の依存関係を削除します。https://www.drupal.org/node/3104677
2. .info.yml の依存関係に js_cookie:js_cookie を追加します(コントリビュート/カスタムのモジュールとテーマ向け)。https://www.drupal.org/project/js_cookie
3. ライブラリの依存関係を js_cookie/js-cookie に変更します。https://www.drupal.org/project/js_cookie
4. 上に示したとおり、JS を $.cookie から Cookies.* へ書き直します。https://www.drupal.org/node/3104677

B)core/js-cookie から js_cookie/js-cookie へ(Drupal 10.1 → 11)

1. モジュールを require します: composer require drupal/js_cookie。https://www.drupal.org/project/js_cookie
2. (コントリビュート).info.yml に js_cookie:js_cookie を追加します。あとはモジュールを有効化するだけです https://www.drupal.org/project/js_cookie。
3. .libraries.yml で、core/js-cookie を js_cookie/js-cookie に置き換えます。https://www.drupal.org/node/3322720
4. 既存の Cookies.* の JS コードはそのまま維持します。機能的な変更は不要です。https://www.drupal.org/node/3322720

落とし穴とベストプラクティス

• Drupal 11 への備え: core/js-cookie は Drupal 11 で削除されます。すべての依存関係が js_cookie/js-cookie を指すようにしてください。https://www.drupal.org/node/3322720
• プライバシー/CDN: js_cookie のプロジェクトページは、js-cookie を CDN から読み込むのを避ける方法(データ保護)を記載しています。ローカルアセットを優先してください。https://www.drupal.org/project/js_cookie
• エンコードと JSON: 暗黙の JSON の挙動に頼らないでください。前述のとおり、明示的に JSON.stringify と JSON.parse を使ってください。https://www.drupal.org/node/3104677
• 実世界のパッチ: 更新時のパターンについては、issue キュー(例:EU Cookie Compliance)を確認してください。https://www.drupal.org/project/eu_cookie_compliance/issues/3380490