Upgrade path for 2.x -> 4.x

Introduction

There have been some major improvements made during the update of Prototype from 2.x to 4.x, from the build tools themselves to the use of CSS variables, folder structure and browser support. Care needs to be taken to be sure that these improvements are reflected without any regression to custom themes that use Prototype as a base.

Below are several pieces to the update for which to keep in mind when upgrading your sites.

Directory Structure

• Final build of all CSS and JavaScript assets has been moved from the /build directory to /dist.
• /components is now under libraries/components
• For the most part, Prototype should have all of the libraries in Drupal’s prototype.libraries.yml file updated, but if your custom theme is referencing Prototype build directories in any way, the path will need to be updated in your custom theme’s libraries file.

Partials

• If your custom theme is referencing any of Prototype’s Functions, Mixins or Settings, many of these have been rewritten and may need to be adjusted in your custom theme.
• If when you are running build tools in your custom theme and running into issues, please reference /themes/contrib/prototype/README.md for a list of current Functions and Mixins with explanations of use.

Globals

• Base styles, such as many of the global settings and base.scss have been cleaned out and improved / modernized.
• If you are noticing any visual regression on your custom site, steps may need to be taken to either re-establish certain theming or libraries may need to be overwritten.

Inline SVGs

• Inline SVGs will no longer use a SASS Function/Mixin, and should be replaced with the new PostCSS plugin function.
• For any custom themes still using the SASS Function/Mixin to inline SVGs, you must rewrite your statements as detailed in the /themes/contrib/prototype/README.md document.
• Example: background: svg-load('image.svg', fill="#000000");
• The PostCSS SVG Inline tool will read directly from any SVGs placed under images/icons

Components

• Many components have been updated and refreshed, similar to the Global files.
• If you are noticing any visual regression on your custom site, steps may need to be taken to either re-establish certain theming or libraries may need to be overwritten.

Replacing Stable with Stable9

This update includes support for Drupal 10; historically Prototype relied on the Stable theme, this has been updated to Stable 9 and includes a post update hook to support this change.

drush 11 vs drush 10

When running drush updb, please make sure you are running drush 11 otherwise you are likely to run into errors.
Run updates via drupal interface if using drush 10 or less.
If errors already appeared, use either drush theme:uninstall classy stable
and/or drush theme:enable stable9 depending on which php errors you received.

config

If using configuration synchronisation, make sure your core.extension.yml contains

theme:
...
stable9: 0

instead of
theme:
...
stable: 0
classy: 0