Support Tailwind CSS v4.0

[alex-fusionauth]

What page of the docs did you find an issue on?

https://starlight.astro.build/guides/css-and-tailwind/#tailwind-css

Describe the issue

The page is out of date for tailwind's new configuration.

What operating system are you using?

Mac

What browser are you using?

Chrome

Participation

• I am willing to submit a pull request for this issue.

[delucis]

Thanks for the issue @alex-fusionauth!

@HiDeoo did take a look at what our options are but the Tailwind v4 docs are weirdly lacking in mentioning how plugins should evolve for v4 (the only mentions are of plugins as “legacy”), so we may need to wait a little for an update to how that works — even official plugins like Tailwind Typography seem not really to have been updated for v4.

In theory, folks should already be able to use the @plugin directive to include the Starlight plugin but there’s some stuff we’re not sure we could support in the new version like the handy way to set the accent colour with an existing Tailwind palette.

[awhitford]

I can't comment on all the Starlight/Tailwind issues, but sharing that DaisyUI is a Tailwind plugin, and you can see that they went from:

  plugins: [
    require('daisyui'),
  ],

to

@plugin "daisyui";

DaisyUI	Tailwind	Installation
v4	v3	https://daisyui.com/docs/install/
v5	v4	https://v5.daisyui.com/docs/install/

[Eveeifyeve]

I am creating a big pr that will fix all of the issues that you are havng, but I need to figure out how lighting css works and tailwind now works to fix the test.

[erkobridee]

Hi all, I managed to migrate my project from the Tailwind CSS v3 to v4 by doing the following changes

erkobridee/astro-starlight-hello#127

Summary:

• removed the dependencies: @astrojs/tailwind and @astrojs/starlight-tailwind
• update the TailwindCSS dep to v4
• add the dep @tailwindcss/vite
• add the Tailwind as a vite plugin at the astro.config.js
• finally, move the previous definitions from the tailwind.config.js into CSS variables
  • the starlight tailwind plugin code, helped me to migrate the code into the CSS >> https://github.com/withastro/starlight/blob/main/packages/tailwind/index.ts

it would be interesting to have this guide added to the starlight docs 😄

[Eveeifyeve]

Well there won't be any need for @astrojs/tailwind but a need for @astrojs/starlight-tailwind.

[erkobridee]

Well, the old way of defining customization to TailwindCSS seems to be deprecated on the v4, so the @astrojs/starlight-tailwind next version probably will need to generate the CSS and auto inject it as a custom CSS, I guess 🤔

The typography plugin was updated to work with the TailwindCSS v4. It might provide some clues to guide the update of the @astrojs/starlight-tailwind

https://github.com/tailwindlabs/tailwindcss-typography

[erkobridee]

I tried to define a local plugin with similar code from the @astrojs/starlight-tailwind and the result didn't work like when that code was used with the TailwindCSS v3

The code that I used locally:

utils/starlightTailwindPlugin.ts

import plugin from 'tailwindcss/plugin';

const starlightTailwindPlugin = plugin(({ addBase, theme, config }) => {
  // TODO: remove
  console.log(`\n\n\nstarlightTailwindPlugin\n\n`);

  if (config('prefix') === 'sl-') {
    console.warn(
      'A Tailwind prefix of "sl-" will clash with Starlight’s built-in styles.\n' +
        'Please set a different prefix in your Tailwind config file.'
    );
  }

  /** Utility to apply accent colors based on a user’s theme config. */
  const themeAccent = (
    shade: 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950,
    fallback: string
  ) =>
    shade === 950
      ? theme(`colors.accent.${shade}`, theme(`colors.accent.900`, fallback))
      : theme(`colors.accent.${shade}`, fallback);

  let white: string = theme('colors.white');
  if (typeof white !== 'string') {
    console.warn(
      `Expected \`colors.white\` in Tailwind theme to be a string, received ${typeof white}.\n` +
        `Try setting a single value, for example \`white: '#fafaf9'\` or \`white: colors.stone[50]\`.`
    );
    // Ensure a usable value for white if the user-configured one is wrong.
    white = '#fff';
  }

  // TODO: remove
  console.log(`theme('colors.gray.700') `, theme('colors.gray.700'));
  console.log(`theme('colors.accent.600') `, theme('colors.accent.600'));
  console.log(`themeAccent(600, '#4f46e5') `, themeAccent(600, '#4f46e5'));

  addBase({
    // Restore crucial styles from Tailwind Preflight: https://tailwindcss.com/docs/preflight
    // Allow adding a border to an element by just adding a border-width. (https://github.com/tailwindcss/tailwindcss/pull/116)
    '*, ::before, ::after': {
      borderWidth: '0',
      borderStyle: 'solid',
      borderColor: theme('colors.gray.200', 'currentColor')
    },

    '::before, ::after': { '--tw-content': '' },

    // Keep base font-family styles even in non-Starlight pages.
    'html, :host': { 'font-family': theme('fontFamily.sans') },
    'code, kbd, samp, pre': { 'font-family': theme('fontFamily.mono') },

    // Wire up Starlight theme to use Tailwind config.
    ':root': {
      // Use Tailwind-configured font families.
      '--sl-font': theme('fontFamily.sans'),
      '--sl-font-mono': theme('fontFamily.mono'),

      // Dark mode Starlight theme variables.
      '--sl-color-white': white,
      '--sl-color-gray-1': theme('colors.gray.200'),
      '--sl-color-gray-2': theme('colors.gray.300'),
      '--sl-color-gray-3': theme('colors.gray.400'),
      '--sl-color-gray-4': theme('colors.gray.600'),
      '--sl-color-gray-5': theme('colors.gray.700'),
      '--sl-color-gray-6': theme('colors.gray.800'),
      '--sl-color-black': theme('colors.gray.900'),
      '--sl-color-accent-low': themeAccent(950, '#1e1b4b'),
      '--sl-color-accent': themeAccent(600, '#4f46e5'),
      '--sl-color-accent-high': themeAccent(200, '#c7d2fe'),

      // Light mode Starlight theme variables
      '&[data-theme="light"]': {
        '--sl-color-white': theme('colors.gray.900'),
        '--sl-color-gray-1': theme('colors.gray.800'),
        '--sl-color-gray-2': theme('colors.gray.700'),
        '--sl-color-gray-3': theme('colors.gray.500'),
        '--sl-color-gray-4': theme('colors.gray.400'),
        '--sl-color-gray-5': theme('colors.gray.300'),
        '--sl-color-gray-6': theme('colors.gray.200'),
        '--sl-color-gray-7': theme('colors.gray.100'),
        '--sl-color-black': white,
        '--sl-color-accent-low': themeAccent(200, '#c7d2fe'),
        '--sl-color-accent': themeAccent(600, '#4f46e5'),
        '--sl-color-accent-high': themeAccent(900, '#312e81')
      }
    }
  });
});

export default starlightTailwindPlugin;

and on the CSS file I imported like: @plugin '~/utils/starlightTailwindPlugin';

I had the confirmation of its execution by the output of the console.log at the terminal

starlightTailwindPlugin


theme('colors.gray.700')  #363935
theme('colors.accent.600')  #1c5800
themeAccent(600, '#4f46e5')  #1c5800

and on the browser this content was placed inside of

@layer base {
  *, ::before, ::after {
    border-width: 0;
    border-style: solid;
    border-color: #eceeec;
  }
  ::before, ::after {
    --tw-content: ;
  }
  html, :host {
    font-family: Poppins, ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji',
    'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
  }
  code, kbd, samp, pre {
    font-family: ui-monospace;
    font-family: SFMono-Regular;
    font-family: Menlo;
    font-family: Monaco;
    font-family: Consolas;
    font-family: "Liberation Mono";
    font-family: "Courier New";
    font-family: monospace;
  }
  :root {
    --sl-font: Poppins, ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji',
    'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
    --sl-font-mono: ui-monospace;
    --sl-font-mono: SFMono-Regular;
    --sl-font-mono: Menlo;
    --sl-font-mono: Monaco;
    --sl-font-mono: Consolas;
    --sl-font-mono: "Liberation Mono";
    --sl-font-mono: "Courier New";
    --sl-font-mono: monospace;
    --sl-color-white: #fff;
    --sl-color-gray-1: #eceeec;
    --sl-color-gray-2: #c0c3c0;
    --sl-color-gray-3: #888d87;
    --sl-color-gray-4: oklch(0.446 0.03 256.802);
    --sl-color-gray-5: #363935;
    --sl-color-gray-6: #242823;
    --sl-color-black: #171917;
    --sl-color-accent-low: #0a2c00;
    --sl-color-accent: #1c5800;
    --sl-color-accent-high: #abd79f;
    &[data-theme="light"] {
      --sl-color-white: #171917;
      --sl-color-gray-1: #242823;
      --sl-color-gray-2: #363935;
      --sl-color-gray-3: #555954;
      --sl-color-gray-4: #888d87;
      --sl-color-gray-5: #c0c3c0;
      --sl-color-gray-6: #eceeec;
      --sl-color-gray-7: #f5f6f5;
      --sl-color-black: #fff;
      --sl-color-accent-low: #abd79f;
      --sl-color-accent: #1c5800;
      --sl-color-accent-high: #113d00;
    }
  }

...
}

which didn't have been applied to the UI

the expected result was the following one

So far I tested it, and it seems the approach to work with the TailwindCSS v4 would be to generate a CSS and inject it as a customCSS, having it similar to:

https://github.com/erkobridee/astro-starlight-hello/blob/f65e8fbae03934682ac4e78f9c7ff3bd79b14d2e/src/assets/styles/starlight.css

I hope that my current findings help the next steps on this topic o/

If anyone else wants to test the code above, it's available here: https://github.com/erkobridee/astro-starlight-hello/tree/feat/starlightTailwindPlugin