Upgrading to 1.1.9

When coming from Hyvä version 1.1.8 or earlier, the biggest change when upgrading to 1.1.9 or later will probably be the switch to the Tailwind CSS JIT compiler.

Please note, that upgrading to the JIT compiler is optional. Existing themes can continue to use the AOT compiler should they so choose.

Warning

The Tailwind CSS AOT compilation mode will be removed from Tailwind CSS version 3.
If you choose to continue to upgrade your theme, the switch to the JIT compiler will have to be done sooner or later.

Tailwind CSS uses a just-in-time (JIT) compiler by default, and will be removing the previously used ahead-of-time (AOT) compilation mode with version 3.

With the release of 1.1.9, Hyvä also uses the JIT compiler by default.

Using the JIT compiler

In 1.1.9 the commands in the packages.json file have been updated.

# build a production bundle using the JIT compiler:
npm run build-prod

# run the JIT compiler continuously for development:
npm run watch

# build an unpurged development bundle using the AOT compiler:
npm run build-dev

It is not possible to generate a unpurged development styles.css file using the JIT compiler.

Because an unpurged CSS file offers some benefits like class name autocompletion in devtools during development, the 1.1.9 release still contains the npm run build-dev command in the package.json to generate an unpurged file using the AOT compiler.

Upgrading an existing Hyvä theme to use the Tailwind CSS JIT compiler

Updating a Hyvä theme to work with the JIT compiler

The JIT compiler is not compatible with the version of the CSS in web/tailwind/ that was shipped with Hyvä versions 1.1.8 and earlier.

Switching to JIT mode

The following line needs to be added to the module.exports section of the tailwind.config.js file:

    mode: 'jit'

With this line in place, any build will be made using the JIT compiler.

To switch back to the AOT compiler, remove the line again, or use

    mode: 'aot'

Making a Hyvä theme without CSS customizations JIT compatible

If there are no customizations a Hyvä theme CSS, upgrading to the JIT requires pulling in the following files from the 1.1.9 release:

web/tailwind/components/button.css
web/tailwind/components/structure.css
web/tailwind/components/typography.css
web/tailwind/theme/components/customer.css
web/tailwind/postcss.config.js

Making a Hyvä theme with CSS customizations JIT compatible

The amount of work required to make an existing custom theme work with the JIT compiler depends on the customizations.

When upgrading the customized Hyvä CSS it is probably easiest to run the JIT compiler and see where it breaks. The error messages are somewhat cryptic, but we hope this document will help you make the appropriate changes until your complete theme compiles with the Tailwind CSS JIT compiler.

Updating the CSS

When adding support for the JIT compiler to Hyvä, we discovered we only needed to make one type of change to the CSS. We needed to wrap any custom CSS class used with @apply within another CSS class with a @layer directive.

Example

In 1.1.8, the following declaration was present in the file web/tailwind/components/button.css. This declares a custom class btn-primary:

.btn-primary {
    @apply bg-primary text-white shadow-md;

    &:hover {
        @apply bg-primary-lighter text-white shadow-lg;
    }
}

In the file web/tailwind/theme/components/customer.css the following declaration applies all classes from btn-primary:

.actions-toolbar .primary button {
    @apply btn btn-primary;
}

This caused the JIT compilation to break. The declaration of the .btn-primary class needed to be wrapped with a @layer components declaration:

@layer components {
    .btn-primary {
        @apply bg-primary text-white shadow-md;

        &:hover {
            @apply bg-primary-lighter text-white shadow-lg;
        }
    }
}

This change had to be made for any custom CSS class that was applied anywhere else in the CSS.

We can use base, components and utilities as layer names.

The name for the layer to use depends on where the generated CSS for that class should end up in the final output.

Tailwind will automatically move those styles to the same place as @tailwind utilities to avoid unintended specificity issues.

Let us have a look at the lines starting with @import "tailwindcss/ in the Hyvä tailwind-source.css file

/* purgecss start ignore */
@import "tailwindcss/base";
@import "tailwindcss/components";

[...]

/* purgecss end ignore */

@import "tailwindcss/utilities";

Here we see that any CSS from base and components will not be purged, because it is placed between the /* purgecss start ignore */ and /* purgecss end ignore */ comments.

Any components declared within the @layer utilities will be purged unless they are used in files within the purge list.

Finally, update your postcss.config.js file to match (especially the tailwindcss/nesting plugin)

module.exports = {
    plugins: [
        require('postcss-import'),
        require('tailwindcss/nesting'),
        require('tailwindcss'),
        require('autoprefixer'),
    ]
}

And that is it.

After wrapping any applied classes in @layer directives, maybe adding the tailwindcss/nesting plugin to the postcss config, and switching to mode: 'jit' in the tailwind.config.jsfile, your customized Hyvä theme should be JIT ready!

Changelogs

Changelogs are available from the CHANGELOG.md in the codebase, or here:

Known Issues

If max allowed quantity in cart is set to 0 in for a product, the quantity field only allows 0.
Gitlab Issue #295 - merge request 355
Resolved in 1.1.10
Can't remove product from compare. On the Product Compare page the "x" button for removing the product from comparison does not work.
Gitlab Issue #300 - merge request 364
Resolved in 1.1.10