Need some first guidiance to upgrade from v3 to v4 when using plugins #18648

TomFreudenberg · 2025-07-31T13:50:14Z

TomFreudenberg
Jul 31, 2025

This is my theme-plugin.ts

/* eslint-disable import/no-extraneous-dependencies */
import defaultTheme from 'tailwindcss/defaultTheme';
import tailwindcssPlugin from 'tailwindcss/plugin';
import tailwindcssBaseFontSizePlugin from 'tailwindcss-base-font-size';
import tailwindcssAnimatePlugin from 'tailwindcss-animate';
import type { Config as tailwindConfig } from 'tailwindcss/types/config';
/* eslint-enable import/no-extraneous-dependencies */

const taperThemePlugin = tailwindcssPlugin(
  ({ addBase, addUtilities, matchUtilities, addVariant, theme }) => {
    // imported CSS classes from original updated global.scss file by ShadcnUI
    addBase({
      body: {
        // for debugging purpose add this style
        // textTransform: 'uppercase'
      },
      ':root': {
        '--background': '0 0% 100%',
        '--foreground': '222.2 84% 4.9%',
        '--card': '0 0% 100%',
        '--card-foreground': '222.2 84% 4.9%',
        '--popover': '0 0% 100%',
        '--popover-foreground': '222.2 84% 4.9%',
        '--primary': '222.2 47.4% 11.2%',
        '--primary-foreground': '189 60.7% 54.1%',
        '--secondary': '210 40% 96.1%',
        '--secondary-foreground': '222.2 47.4% 11.2%',
        '--muted': '210 40% 96.1%',
        '--muted-foreground': '215.4 16.3% 46.9%',
        '--accent': '210 40% 96.1%',
        '--accent-foreground': '222.2 47.4% 11.2%',
        '--destructive': '0 84.2% 60.2%',
        '--destructive-foreground': '210 40% 98%',
        '--shadow': '214.3 31.8% 85.4%',
        '--border': '214.3 31.8% 91.4%',
        '--input': '214.3 31.8% 91.4%',
        '--ring': '189 60.7% 54.1%',
        '--radius': '0.5rem',
      },
      '.dark': {
        '--background': '222.2 84% 4.9%',
        '--foreground': '210 40% 98%',
        '--card': '222.2 84% 4.9%',
        '--card-foreground': '210 40% 98%',
        '--popover': '222.2 84% 4.9%',
        '--popover-foreground': '210 40% 98%',
        '--primary': '210 40% 98%',
        '--primary-foreground': '222.2 47.4% 11.2%',
        '--secondary': '217.2 32.6% 17.5%',
        '--secondary-foreground': '210 40% 98%',
        '--muted': '217.2 32.6% 17.5%',
        '--muted-foreground': '215 20.2% 65.1%',
        '--accent': '217.2 32.6% 17.5%',
        '--accent-foreground': '210 40% 98%',
        '--destructive': '0 62.8% 30.6%',
        '--destructive-foreground': '210 40% 98%',
        '--shadow': '217 4% 38%',
        '--border': '217.2 32.6% 17.5%',
        '--input': '217.2 32.6% 17.5%',
        '--ring': '212.7 26.8% 83.9%',
      },
    });

    // imported CSS styles on components
    addBase({
      '*': {
        '@apply border-border': {},
        '--tw-shadow-color': 'hsl(var(--shadow))',
      },
      html: {
        'scroll-behavior': 'smooth',
      },
      body: {
        '@apply font-sans': {},
        '@apply bg-background text-foreground': {},
      },
    });

    addUtilities({
      '.inherit-font-weight': {
        fontWeight: 'inherit',
      },
      '.inherit-font-size': {
        fontSize: 'inherit',
      },
      '.inherit-line-height': {
        lineHeight: 'inherit',
      },
    });

    // config additional plugin function
    matchUtilities(
      {
        'text-shadow': (value) => ({
          textShadow: value,
        }),
      },
      {
        values: theme('textShadow'),
      }
    );

    // append @media selectors
    // using screens is deprecated
    addVariant('ws', '@media (min-aspect-ratio: 3/2) and (max-height: 399px)');
  },

  // extend the theme configuration
  {
    // per default we set the light / dark theme by activating
    // className="dark" on <html> main
    darkMode: 'class',
    // config the theme and align to css styles from base
    theme: {
      container: {
        center: true,
        padding: '2rem',
      },
      screens: {
        // it is important to override the screens config
        // otherwise the css is not sorted correctly and
        // then some of the new states will overrule the
        // more fitting rules while later in source.
        xs: '360px',
        ...defaultTheme.screens,
      },
      extend: {
        fontFamily: {
          sans: ['var(--font-sans-app)', 'Verdana', 'Helvetica', 'sans-serif'],
          mono: ['var(--font-mono-app)', 'Courier', 'Courier New', 'Andale Mono', 'mono'],
          serif: ['var(--font-serif-app)', 'Times', 'Times New Roman', 'Georgia', 'serif'],
          highlight: ['Comic Sans MS', 'Helvetica', 'sans', 'sans-serif'],
        },
        backgroundImage: {
          // hero-background is loaded from global scss while tailwind does not support image-set
          'hero-background': '', // 'url("/assets/hero-background.webp")',
        },
        colors: {
          // custom colors
          'nd-blue': '#00adbc',
          'nd-blue-200': '#00bedd',
          'nd-blue-ui': '#009fad',
          'nd-blue-text': '#00838f',
          'nd-red': '#cf2463',
          'nd-red-200': '#de266a',
          'tonies-red': '#d3000f',
          'tonies-lblue': '#94cedc',
          // overwrite styles
          border: 'hsl(var(--border))',
          input: 'hsl(var(--input))',
          ring: 'hsl(var(--ring))',
          background: 'hsl(var(--background))',
          foreground: 'hsl(var(--foreground))',
          primary: {
            DEFAULT: 'hsl(var(--primary))',
            foreground: 'hsl(var(--primary-foreground))',
          },
          secondary: {
            DEFAULT: 'hsl(var(--secondary))',
            foreground: 'hsl(var(--secondary-foreground))',
          },
          destructive: {
            DEFAULT: 'hsl(var(--destructive))',
            foreground: 'hsl(var(--destructive-foreground))',
          },
          muted: {
            DEFAULT: 'hsl(var(--muted))',
            foreground: 'hsl(var(--muted-foreground))',
          },
          accent: {
            DEFAULT: 'hsl(var(--accent))',
            foreground: 'hsl(var(--accent-foreground))',
          },
          popover: {
            DEFAULT: 'hsl(var(--popover))',
            foreground: 'hsl(var(--popover-foreground))',
          },
          card: {
            DEFAULT: 'hsl(var(--card))',
            foreground: 'hsl(var(--card-foreground))',
          },
        },
        borderRadius: {
          lg: 'var(--radius)',
          md: 'calc(var(--radius) - 2px)',
          sm: 'calc(var(--radius) - 4px)',
        },
        textShadow: {
          sm: '1px 1px 2px var(--tw-shadow-color)',
          DEFAULT: '2px 2px 4px var(--tw-shadow-color)',
          lg: '4px 4px 8px var(--tw-shadow-color)',
          xl: '8px 8px 16px var(--tw-shadow-color)',
        },
        keyframes: {
          'accordion-down': {
            from: { height: '0' },
            to: { height: 'var(--radix-accordion-content-height)' },
          },
          'accordion-up': {
            from: { height: 'var(--radix-accordion-content-height)' },
            to: { height: '0' },
          },
          'slow-in': {
            from: { opacity: '0' },
            to: { opacity: '1' },
          },
          'scale-in': {
            from: { opacity: '0', transform: 'scale(1.3)' },
            to: { opacity: '1', transform: 'scale(1)' },
          },
        },
        animation: {
          'accordion-down': 'accordion-down 0.2s ease-out',
          'accordion-up': 'accordion-up 0.2s ease-out',
          'slow-in': 'slow-in 0.5s cubic-bezier(0.1, 0, 0.3, 1)',
          'scale-in': 'scale-in 0.3s cubic-bezier(0.2, 0, 0.7, 1)',
        },
      },
    },
  }
);

// apply some theming necessaries
const taperThemePluginAddons = [
  tailwindcssBaseFontSizePlugin({
    baseFontSize: 18,
  }),
  tailwindcssAnimatePlugin,
];

const withTaperThemePlugin = (config: Partial<tailwindConfig>) => {
  // the order will define latest setting wins
  return [taperThemePluginAddons, taperThemePlugin, config];
};

export { withTaperThemePlugin };

I tried to understand the migration to v4 but I struggle on:

import defaultTheme from 'tailwindcss/defaultTheme';
import tailwindcssPlugin from 'tailwindcss/plugin';
import tailwindcssBaseFontSizePlugin from 'tailwindcss-base-font-size';
import tailwindcssAnimatePlugin from 'tailwindcss-animate';
addBase({
addUtilities({
matchUtilities(
addVariant('ws', '@media (min-aspect-ratio: 3/2) and (max-height: 399px)');
// extend the theme configuration
{ ....

I really would be happy if some could guide me with some links or patterns.

Thanks
Tom

Answered by wongjn

Jul 31, 2025

1. `import defaultTheme from 'tailwindcss/defaultTheme';`

There is no real equivalent. I can see you're only using it here:

screens: {
  // it is important to override the screens config
  // otherwise the css is not sorted correctly and
  // then some of the new states will overrule the
  // more fitting rules while later in source.
  xs: '360px',
  ...defaultTheme.screens,
},

But this hasn't been neccessary since perhaps v3.3 or v3.4 - breakpoints are sorted for you most of the time. You can do:

@theme {
  --breakpoint-xs: 22.5rem;
}

Note that it's important to always use the same unit for defining your breakpoints or the generated utilities may be sorted in an unexpected order, causing …

View full answer

wongjn · 2025-07-31T18:56:50Z

wongjn
Jul 31, 2025
Collaborator

1. `import defaultTheme from 'tailwindcss/defaultTheme';`

There is no real equivalent. I can see you're only using it here:

screens: {
  // it is important to override the screens config
  // otherwise the css is not sorted correctly and
  // then some of the new states will overrule the
  // more fitting rules while later in source.
  xs: '360px',
  ...defaultTheme.screens,
},

But this hasn't been neccessary since perhaps v3.3 or v3.4 - breakpoints are sorted for you most of the time. You can do:

@theme {
  --breakpoint-xs: 22.5rem;
}

Note that it's important to always use the same unit for defining your breakpoints or the generated utilities may be sorted in an unexpected order, causing breakpoint classes to override each other in unexpected ways.

Tailwind uses rem for the default breakpoints, so if you are adding additional breakpoints to the defaults, make sure you use rem as well.

https://tailwindcss.com/docs/responsive-design#customizing-your-theme

2. `import tailwindcssPlugin from 'tailwindcss/plugin';`

There is no real equivalent.

3. `import tailwindcssBaseFontSizePlugin from 'tailwindcss-base-font-size';`

If tailwindcss-base-font-size is using the legacy JavaScript based API, you'd do:

@plugin "tailwindcss-base-font-size" {
  baseFontSize: 18,
};

Otherwise, you'd do something like:

@import "tailwindcss-base-font-size";

https://tailwindcss.com/docs/functions-and-directives#plugin-directive

4. `import tailwindcssAnimatePlugin from 'tailwindcss-animate';`

If tailwindcss-base-font-size is using the legacy JavaScript based API, you'd do:

@plugin "tailwindcss-animate";

Otherwise, you'd do something like:

@import "tailwindcss-animate";

https://tailwindcss.com/docs/functions-and-directives#plugin-directive

5. `addBase({`

You'd add rules to @layer base.

@layer base {
  * {
    @apply border-border;
    --tw-shadow-color: hsl(var(--shadow));
  }

  html {
    scroll-behavior: smooth;
  }

  …
}

https://tailwindcss.com/docs/adding-custom-styles#adding-base-styles

6. `addUtilities({`

You'd use @utility like:

@utility inherit-font-weight {
  font-weight: inherit;
}

https://tailwindcss.com/docs/adding-custom-styles#simple-utilities

7. `matchUtilities({`

You'd use @utility like:

@utility text-shadow-* {
  text-shadow: var(--text-shadow-*, [*]);
}

https://tailwindcss.com/docs/adding-custom-styles#functional-utilities

8. `addVariant('ws', '@media (min-aspect-ratio: 3/2) and (max-height: 399px)');`

You'd use @custom-variant like:

@custom-variant ws (@media (min-aspect-ratio: 3/2) and (max-height: 399px));

https://tailwindcss.com/docs/adding-custom-styles#adding-custom-variants

9. `// extend the theme configuration`

You'd use a @theme block like:

@theme {
  --color-nd-blue: #00adbc;
  --color-nd-blue-200: #00bedd;
  --color-nd-blue-ui: #009fad;
  …
}

https://tailwindcss.com/docs/theme

3 replies

TomFreudenberg Jul 31, 2025
Author

@wongjn thanks for your helpful answer, I will try my way thru

TomFreudenberg Aug 7, 2025
Author

Dear @wongjn Justin

thanks to your help, I could rewrite all my theme and adoptions from v3 to v4 and it is running in a 1:1 manner. That is super - you guided me the right direction.

One question left:

const config: Config = {
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}'
  ],

Do you know for an equivalent content config in v4 or is that obsolete?

I couldn't find anything in the documentation yet.

For others: this was also a helpful entry on medium:

https://medium.com/@genildocs/tailwind-css-4-sass-why-they-dont-mix-and-what-to-do-about-it-94598e0f1342

and a helpful tool to convert hsl color to neq oklch

https://oklchtools.com/

wongjn Aug 7, 2025
Collaborator

It is generally obsolete - you shouldn't need to port that across since v4 has automatic source detection.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Need some first guidiance to upgrade from v3 to v4 when using plugins #18648

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment 3 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

Need some first guidiance to upgrade from v3 to v4 when using plugins #18648

Uh oh!

TomFreudenberg Jul 31, 2025

1. import defaultTheme from 'tailwindcss/defaultTheme';

Replies: 1 comment · 3 replies

Uh oh!

Uh oh!

wongjn Jul 31, 2025 Collaborator

1. import defaultTheme from 'tailwindcss/defaultTheme';

2. import tailwindcssPlugin from 'tailwindcss/plugin';

3. import tailwindcssBaseFontSizePlugin from 'tailwindcss-base-font-size';

4. import tailwindcssAnimatePlugin from 'tailwindcss-animate';

5. addBase({

6. addUtilities({

7. matchUtilities({

8. addVariant('ws', '@media (min-aspect-ratio: 3/2) and (max-height: 399px)');

9. // extend the theme configuration

Uh oh!

TomFreudenberg Jul 31, 2025 Author

Uh oh!

Uh oh!

TomFreudenberg Aug 7, 2025 Author

Uh oh!

wongjn Aug 7, 2025 Collaborator

TomFreudenberg
Jul 31, 2025

1. `import defaultTheme from 'tailwindcss/defaultTheme';`

Replies: 1 comment 3 replies

wongjn
Jul 31, 2025
Collaborator

1. `import defaultTheme from 'tailwindcss/defaultTheme';`

2. `import tailwindcssPlugin from 'tailwindcss/plugin';`

3. `import tailwindcssBaseFontSizePlugin from 'tailwindcss-base-font-size';`

4. `import tailwindcssAnimatePlugin from 'tailwindcss-animate';`

5. `addBase({`

6. `addUtilities({`

7. `matchUtilities({`

8. `addVariant('ws', '@media (min-aspect-ratio: 3/2) and (max-height: 399px)');`

9. `// extend the theme configuration`

TomFreudenberg Jul 31, 2025
Author

TomFreudenberg Aug 7, 2025
Author

wongjn Aug 7, 2025
Collaborator