Migrating

v5.x.x

Migrating from A17 Tailwind Plugins 4 to A17 Tailwind Plugins 5

terminal
npm install @area17/a17-tailwind-plugins@latest

Ensure your screens, mainColWidths, innerGutters, outerGutters and columnCount are defined at all breakpoints

Previously you could define just the breakpoints where the gutters changed:

tailwind.config.js
const { Setup } = require('@area17/a17-tailwind-plugins');

module.exports = {
  ...
  plugins: [Setup],
  theme: {
    screens: {
      xs: "0",
      sm: "544px",
      md: "650px",
      lg: "990px",
      xl: "1300px",
      xxl: "1520px"
    },
    mainColWidths: {
      xs: "auto",
      xxl: "1440px"
    },
    innerGutters: {
      xs: "10px",
      xxl: "40px"
    },
    outerGutters: {
      xs: "20px",
      sm: "30px",
      xxl: "0px"
    },
    columnCount: {
      xs: "4",
      sm: "4",
      md: "8",
      lg: "12",
      xl: "12",
      xxl: "12"
    },
  }
  ...
};

This was unintentional and no longer works, so you'll need:

tailwind.config.js
const { Setup } = require('@area17/a17-tailwind-plugins');

module.exports = {
  ...
  plugins: [Setup],
  theme: {
    screens: {
      xs: "0",
      sm: "544px",
      md: "650px",
      lg: "990px",
      xl: "1300px",
      xxl: "1520px"
    },
    mainColWidths: {
      xs: "auto",
      sm: "auto",
      md: "auto",
      lg: "auto",
      xl: "auto",
      xxl: "1440px"
    },
    innerGutters: {
      xs: "10px",
      sm: "15px",
      md: "20px",
      lg: "30px",
      xl: "40px",
      xxl: "40px"
    },
    outerGutters: {
      xs: "20px",
      sm: "30px",
      md: "40px",
      lg: "40px",
      xl: "40px",
      xxl: "0px"
    },
    columnCount: {
      xs: "4",
      sm: "4",
      md: "8",
      lg: "12",
      xl: "12",
      xxl: "12"
    },
  }
  ...
};

Migrate Layout class names

See Layout/Breaking changes in v5.0.0

  1. Search for (\w*)-(\d\/\d|\d*)-cols(-no-gutter|-vw)?
  2. Replace with $1-cols$3-$2

And for any fraction class usage:

  1. Search for (\w*)-(\d\/\d)-cols
  2. Replace with $1-cols-$2

Migrate font family settings:

In your frontend.config.json you may have have had:

frontend.config.json
"font-family": "var(--sans)",

Font classes now have a prepended font-. So, you'll need to update to:

frontend.config.json
"font-family": "var(--font-sans)",

Migrate any CSS in config JSON

You'll need to move any styles specified in your config to inside your CSS if you used these plugins.

Migrating from Tailwind 3 to Tailwind 4

Tailwind provide an upgrade guide, you may need to do a mix of automatic and manual updates. Check those changes from v3 class name renames and removals.

Remove tokens from spacing in the config JSON

You no longer require the Spacing tokens plugin or setup:

frontend.config.json
"tokens": {
    "scaler": 4,
    "arbitraries": {
      "400": "400px",
      "600": "600px"
    }
  },

Instead you add:

input.css
@theme {
  --spacing: 1px;
}

Confirm updates to your tailwind.config.js, input.css and postcss.config.js

tailwind.config.js
// A17 tailwind plugins
const {
  Setup,
  ColorTokens,
  ApplyColorVariables,
  Typography,
  Container,
  DevTools,
  GridGap,
  GridLayout,
  Spacing,
  Layout,
  GridLine,
  Keyline,
  BackgroundFill,
  StrokeFull,
  Underline,
  FullBleedScroller,
  Scrollbar,
  PseudoElements,
  InteractionMediaQueries,
  RatioBox,
} = require('../index');

// conf
const feConfig = require('./frontend.config.json');

module.exports = {
  content: ['./docs/**/*.html', './docs/*.html'],
  plugins: [
    Setup,
    ColorTokens,
    ApplyColorVariables,
    Typography,
    Container,
    DevTools,
    GridGap,
    GridLayout,
    Spacing,
    Layout,
    GridLine,
    Keyline,
    BackgroundFill,
    StrokeFull,
    Underline,
    FullBleedScroller,
    Scrollbar,
    PseudoElements,
    InteractionMediaQueries,
    RatioBox,
  ],
  theme: {
    screens: feConfig.structure.breakpoints,
    mainColWidths: feConfig.structure.container,
    innerGutters: feConfig.structure.gutters.inner,
    outerGutters: feConfig.structure.gutters.outer,
    columnCount: feConfig.structure.columns,
    fontFamilies: feConfig.typography.families,
    typesets: feConfig.typography.typesets,
    spacingGroups: feConfig.spacing.groups,
    ratios: feConfig.ratios,
    css: feConfig.css,
    colors: feConfig.color.tokens,
    borderColor: ApplyColorVariables(
      feConfig.color.tokens,
      feConfig.color.border
    ),
    textColor: ApplyColorVariables(feConfig.color.tokens, feConfig.color.text),
    backgroundColor: ApplyColorVariables(
      feConfig.color.tokens,
      feConfig.color.background
    ),
    underlineColor: ApplyColorVariables(
      feConfig.color.tokens,
      feConfig.color.underline
    ),
    scrollbarColor: {
      track: ApplyColorVariables(
        feConfig.color.tokens,
        feConfig.color.scrollbar.track
      ),
      thumb: ApplyColorVariables(
        feConfig.color.tokens,
        feConfig.color.scrollbar.thumb
      ),
    },
  },
  extend: {
    spacing: {
      gutter: 'var(--inner-gutter)',
      'outer-gutter': 'var(--outer-gutter, 0px)',
    },
  },
};
input.css
@config "./tailwind.config.js";
@import "tailwindcss";

@theme {
  --container-*: initial;
  --breakpoint-*: initial;
  --color-*: initial;
  --font-*: initial;
  --text-*: initial;
  --tracking-*: initial;
  --leading-*: initial;
  --spacing: 1px;
}

@utility container {
  max-width: 100%;
}
postcss.config.js
module.exports = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

Vite config

If you're using Vite, you'll want to swap to import tailwindcss from '@tailwindcss/vite' and not use post CSS to compile, so you'll end up with a vite.config.js something like:

vite.config.js
import eslintPlugin from '@nabla/vite-plugin-eslint'
import tailwindcss from '@tailwindcss/vite'
import laravel from 'laravel-vite-plugin'
import { resolve } from 'path'
import { defineConfig } from 'vite'
import dynamicImport from 'vite-plugin-dynamic-import'
import environmentPlugin from 'vite-plugin-environment'
import manifestSRI from 'vite-plugin-manifest-sri'

export default ({ mode }) => {
    return defineConfig({
        server: {
            host: 'sitename.test'
        },
        plugins: [
            tailwindcss(),
            dynamicImport(),
            eslintPlugin(),
            environmentPlugin({
                MODE: mode,
                BEHAVIORS_PATH: resolve(
                    __dirname,
                    'resources/frontend/scripts/behaviors'
                ),
                BEHAVIORS_EXTENSION: 'js'
            }),
            laravel({
                input: [
                    resolve(__dirname, 'resources/frontend/styles/app.css'),
                    resolve(__dirname, 'resources/frontend/scripts/app.js')
                ],
                refresh: true
            }),
            manifestSRI()
        ],
        resolve: {
            alias: {
                '@': resolve(__dirname, 'resources/frontend'),
                '@root': resolve(__dirname, './'),
                '@vitrineUI': resolve(__dirname, 'vendor/area17/vitrine-ui'),
                '@vitrineUIComponents': resolve(
                    __dirname,
                    'vendor/area17/vitrine-ui/resources/views/components/'
                )
            }
        }
    })
}

Stylelint

You may also want to update your stylelint.config.js:

stylelint.config.js
{
    "extends": ["stylelint-config-standard", "stylelint-config-clean-order"],
    "rules": {
        "custom-property-pattern": null,
        "at-rule-no-unknown": [
            true,
            {
                "ignoreAtRules": [
                    "config",
                    "custom-variant",
                    "source",
                    "theme",
                    "utility",
                    "variant"
                ]
            }
        ],
        "at-rule-no-deprecated": [
            true,
            {
                "ignoreAtRules": ["apply"]
            }
        ],
        "import-notation": "string",
        "function-no-unknown": [
            true,
            {
                "ignoreFunctions": ["theme"]
            }
        ],
        "no-descending-specificity": null
    },
    "ignoreFiles": [
        "node_modules/**/*",
        "public/build/**/*"
    ]
}

Migrate classes

And then you'll have fun migrating classes. For example:

  • Arbitrary spacing using a pixel value doesn’t work anymore. Replace left-[-99999px] with -left-99999
  • flex-shrink-0 has been replaced by shrink-0

Tailwind has a list of renamed utilities. and some removed utilities.

Migrate CSS

If you have any CSS in your project, you may want to update to use @utility and @layer components {}

For example:

effect.css
.effect-hidden-fade {
  @apply pointer-events-none invisible opacity-0;

  will-change: opacity, visibility;
  transition:
      opacity 300ms cubic-bezier(0, 0, 0.58, 1) 50ms,
      visibility 0s 351ms;
}

becomes:

effect.css
@utility effect-hidden-fade {
  @apply pointer-events-none invisible opacity-0;

  will-change: opacity, visibility;
  transition:
      opacity 300ms cubic-bezier(0, 0, 0.58, 1) 50ms,
      visibility 0s 351ms;
}

And:

effect.css
.wysiwyg * {
    @apply f-body;
}

.wysiwyg h2,
.wysiwyg h3,
.wysiwyg h4 {
    @apply f-body font-bold text-balance mt-group-6;
}

.wysiwyg p {
    @apply text-pretty;
}

becomes:

effect.css
@layer components {
    .wysiwyg * {
        @apply f-body;
    }

    .wysiwyg h2,
    .wysiwyg h3,
    .wysiwyg h4 {
        @apply f-body font-bold text-balance mt-group-6;
    }

    .wysiwyg p {
        @apply text-pretty;
    }
}