Como reescrever o jQuery Cookie e a biblioteca core/js-cookie no Drupal com o módulo js_cookie

Visão geral do caminho de migração

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

Contexto histórico: o Drupal 9 substituiu o jQuery Cookie pelo js-cookie e forneceu exemplos de mapeamento de código e bibliotecas. https://www.drupal.org/node/3104677

# ANTES (Drupal 8 / início do 9)
my_library:
  js:
    js/my_library.js: {}
  dependencies:
    - core/jquery
    - core/jquery.cookie
    - core/drupal

// ANTES (API jQuery Cookie)
(($, 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);

Depois (Drupal 9), você dependia de core/js-cookie e usava a API Cookies.*: https://www.drupal.org/node/3104677

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

// DEPOIS (Drupal 9, API js-cookie)
((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+ e 11: core/js-cookie → js_cookie (módulo contribuído)

Como o núcleo do Drupal declarou core/js-cookie obsoleta no 10.1 e a removeu no 11, é necessário substituí-la pela biblioteca do módulo JS Cookie: js_cookie/js-cookie. https://www.drupal.org/node/3322720

Composer

composer require drupal/js_cookie

Isso instala o módulo que fornece a biblioteca de assets do Drupal para o pacote original js-cookie. https://www.drupal.org/project/js_cookie

Declaração da dependência do módulo/tema (para projetos contrib/personalizados)

# my_module.info.yml (ou o .info.yml do seu tema)
name: My Module
type: module
core_version_requirement: ^10 || ^11
dependencies:
  - js_cookie:js_cookie

Na página do projeto, indica-se que, para módulos contrib, deve-se adicionar explicitamente js_cookie:js_cookie como dependência (e adicionar drupal/js_cookie no composer, se o módulo tiver o seu próprio composer.json). [4]

Troca da dependência da biblioteca de assets

# Substitua isto (obsoleto no 10.1, removido no 11)
# - core/js-cookie

# Por isto (fornecido pelo módulo contrib)
my_library:
  js:
    js/my_library.js: {}
  dependencies:
    - core/drupal
    - js_cookie/js-cookie

É exatamente essa a substituição recomendada na nota oficial de mudança do núcleo. [2]

Código JavaScript

O seu código JS não exige mudanças se você já usava a API Cookies do js-cookie — muda apenas a dependência da biblioteca. [2]

((Drupal, Cookies) => {
  Drupal.behaviors.myModule = {
    attach: () => {
      // Definir o cookie.
      Cookies.set('cutest', 'red panda', { path: '/', sameSite: 'Lax' });

      // Obter o cookie.
      const myCookieValue = Cookies.get('cutest');

      // Remover o cookie.
      Cookies.remove('cutest', { path: '/' });

      // Salvar/obter JSON com segurança.
      Cookies.set('cutest', JSON.stringify({ animal: 'red panda' }));
      const cutestRaw = Cookies.get('cutest');
      const cutest = cutestRaw ? JSON.parse(cutestRaw) : null;
    },
  };
})(Drupal, window.Cookies);

Dica: o js-cookie está em conformidade com o padrão RFC 6265 e codifica os dados de forma diferente do antigo jQuery Cookie, especialmente para JSON. A nota de mudança do Drupal 9 descreve essas diferenças. https://www.drupal.org/node/3104677

Exemplos do ecossistema

• O módulo EU Cookie Compliance acompanhava a descontinuação de core/js-cookie e foram propostos patches para a migração para js_cookie/js-cookie. https://www.drupal.org/project/eu_cookie_compliance/issues/3380490
• Vários projetos contrib criaram issues para substituir o jQuery Cookie pelo js-cookie e, depois, para resolver a descontinuação de core/js-cookie. https://www.drupal.org/project/quicktabs/issues/3298649
  https://www.drupal.org/project/fpa/issues/3505122