[Advanced]: Upgrade to tailwindcss from 3.4.19 to 4.2.1+

[exploreriii]

🧠 Advanced Contributors

This issue is intended for contributors who are already very familiar with the
Hiero Website codebase and its architectural patterns.

You should feel comfortable with:

• Netlify previews and tests
• Hugo content, layouts, templates, and shortcodes
• The full Hiero website structure and build process
• Reviewing changes holistically, not file-by-file
• Anticipating downstream and maintenance impact
• Communicating design decisions clearly in PRs

New developers should start with
Good First Issues or Beginner Issues first.

🐞 Problem Description

We should be using a latest version of https://github.com/tailwindlabs/tailwindcss/tree/HEAD/packages/tailwindcss

bump tailwindcss from 3.4.19 to 4.2.1

Unfortunately, we are currently using quite an old version which means a lot may have changed.
The build might not work correctly by upgrading to 4.2.1 all in one go.

💡 Proposed / Expected Solution

We should try to upgrade to the recent release https://github.com/tailwindlabs/tailwindcss/tree/HEAD/packages/tailwindcss, but in this process, upgrade any other complementary packages or fix any build issues.

🧠 Implementation & Design Notes

This might be a sensitive upgrade and we will have to check what might need to change

✅ Acceptance Criteria

To merge this issue, the pull request must:

• Fully address the problem and design goals described above
• Maintain backwards compatibility unless explicitly approved otherwise
• Follow existing architectural and coding conventions
• Include comprehensive tests covering new and existing behavior
• Update relevant examples and documentation
• Pass all CI checks
• Include a valid changelog entry
• Use DCO and GPG-signed commits

📚 Additional Context, Links, or Prior Art

Optional.

[exploreriii]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Migrate to Tailwind v4 using the PostCSS approach with @tailwindcss/postcss, maintaining the existing Hugo asset pipeline pattern
• Keep the JavaScript configuration file and load it via the new @config CSS directive to preserve custom theme values
• Update CSS entry file to use v4's @import "tailwindcss" syntax and @source directives for content scanning
• Fix the Netlify build command to run the full npm build pipeline, ensuring CSS compilation occurs during deployment

Design Choices

Design Choice 1: CSS Processing Approach for v4

Options Considered:

1. Continue with PostCSS approach using @tailwindcss/postcss plugin - aligns with existing Hugo template pipeline
2. Switch to Hugo's built-in css.TailwindCSS pipe (requires Hugo 0.128.0+) - cleaner integration but requires more changes

Chosen Option: 1

Rationale: Continue with PostCSS approach using @tailwindcss/postcss. This minimizes changes to the existing Hugo template structure and maintains compatibility with the current asset pipeline pattern.

Design Choice 2: Tailwind Configuration Format

Options Considered:

1. Keep existing tailwind.config.js and reference it via @config directive - simpler migration, minimal risk
2. Migrate entire config to CSS variables and @theme directive - v4-native approach but higher effort and risk

Chosen Option: 1

Rationale: Keep the existing JavaScript configuration file and load it using the @config directive in the CSS entry file. This preserves the custom color palette, typography, and font configurations without requiring a full rewrite.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Dependency and Package Configuration Updates

Update the project's npm dependencies to Tailwind v4 and its companion packages, removing deprecated packages and ensuring the PostCSS toolchain is properly configured.

Task 1: Update npm Dependencies

Install Tailwind CSS v4 and its new PostCSS plugin, remove packages that are no longer needed or are handled natively by v4.

• Update package.json to set tailwindcss to ^4.2.1
• Add @tailwindcss/postcss as a devDependency (replaces tailwindcss as the PostCSS plugin)
• Remove autoprefixer dependency (v4 handles vendor prefixing internally)
• Remove postcss-import from dependencies if present (v4 handles imports internally)
• Verify postcss and postcss-cli versions are compatible with v4 requirements
• Run npm install to update package-lock.json

Task 2: Update PostCSS Configuration

Simplify the PostCSS config to use v4's unified plugin that handles nesting, imports, and prefixing automatically.

• Update postcss.config.js to use only @tailwindcss/postcss as the plugin
• Remove tailwindcss/nesting plugin entry (CSS nesting is native in v4)
• Remove autoprefixer plugin entry (handled by v4)
• Remove postcss-import plugin entry (handled by v4)
• Consider converting to ESM format (postcss.config.mjs) for consistency with modern tooling

🤖 Prompt for AI agents

Update the project's npm dependencies to Tailwind CSS v4 and configure the
PostCSS toolchain. The goal is to replace deprecated packages with v4-compatible
alternatives while ensuring the PostCSS pipeline is properly set up.

**Update package.json:**
- Set `tailwindcss` to version `^4.2.1`
- Add `@tailwindcss/postcss` as a devDependency (this replaces `tailwindcss` as
the PostCSS plugin in v4)
- Remove `autoprefixer` dependency (v4 handles vendor prefixing internally)
- Remove `postcss-import` from dependencies if present (v4 handles imports
internally)
- Verify that `postcss` and `postcss-cli` versions are compatible with Tailwind
v4 requirements
- Run `npm install` to generate updated `package-lock.json`

**Update postcss.config.js:**
- Replace the plugins array to use only `@tailwindcss/postcss` as the single
plugin
- Remove the `tailwindcss/nesting` plugin entry (CSS nesting is now native in
v4)
- Remove the `autoprefixer` plugin entry (now handled internally by v4)
- Remove the `postcss-import` plugin entry (now handled internally by v4)
- Optionally convert the file to ESM format (`postcss.config.mjs`) for
consistency with modern tooling

Phase 2: CSS and Configuration Migration

Migrate the CSS entry file to v4 syntax and ensure the existing Tailwind configuration is properly loaded.

Task 1: Update CSS Entry File Syntax

Convert the main CSS file from v3 directives to v4's import-based approach.

• In assets/css/main.css, replace the three @tailwind directives with @import "tailwindcss"
• Add @config "../../tailwind.config.js" directive to explicitly load the JavaScript configuration
• Add @source "../../content" and @source "../../layouts" directives to specify content scanning paths (replacing the content array from JS config)
• Preserve all existing custom CSS, @apply directives, and nested selectors below the imports

Task 2: Verify Tailwind Configuration Compatibility

Review the existing JavaScript config for v4 compatibility and make necessary adjustments.

• Review tailwind.config.js for deprecated options that v4 no longer supports (corePlugins, safelist, separator)
• Verify the custom theme configuration (colors, fonts, fontSizes) remains valid under v4
• Remove the content array from the JS config (moved to @source directives in CSS)
• Ensure extend properties in theme configuration are compatible with v4's theme structure
• Remove any JIT-specific configurations (JIT is always enabled in v4)

🤖 Prompt for AI agents

Migrate the CSS entry file to Tailwind v4 syntax and update the JavaScript
configuration for compatibility. The goal is to adopt v4's import-based approach
while maintaining the existing JavaScript configuration file.

**Update assets/css/main.css:**
- Replace the three separate `@tailwind` directives (base, components,
utilities) with a single `@import "tailwindcss"` statement
- Add `@config "../../tailwind.config.js"` directive to explicitly load the
existing JavaScript configuration file
- Add `@source "../../content"` and `@source "../../layouts"` directives to
specify content scanning paths (this replaces the `content` array previously in
the JS config)
- Preserve all existing custom CSS, `@apply` directives (62 instances), and
nested selectors below the import statements

**Update tailwind.config.js:**
- Review and remove any deprecated options that v4 no longer supports:
`corePlugins`, `safelist`, `separator`
- Verify the custom `theme` configuration (colors, fonts, fontSizes) remains
valid under v4's structure
- Remove the `content` array from the configuration (content scanning is now
handled by `@source` directives in the CSS file)
- Ensure `extend` properties in the theme configuration are compatible with v4's
theme structure
- Remove any JIT-specific configurations (JIT mode is always enabled in v4)

Phase 3: Build Pipeline and Deployment Updates

Update build scripts and deployment configuration to properly compile CSS with Tailwind v4.

Task 1: Update npm Build Scripts

Modify the build scripts to use v4's CLI syntax and remove deprecated flags.

• In package.json, update all tailwindcss CLI invocations to use the v4 CLI
• Remove the --jit flag from all CLI commands (JIT is always-on in v4)
• Update the CLI path if needed (verify ./node_modules/tailwindcss/lib/cli.js still exists in v4 package structure, or switch to npx tailwindcss)
• Verify the input/output paths remain correct: ./assets/css/main.css → ./static/css/main.css
• Test both npm run start (development) and npm run build (production) commands

Task 2: Fix Netlify Build Configuration

Correct the Netlify build command to ensure CSS is properly compiled during deployment.

• Update netlify.toml build command from npm run fetch-stats && hugo to npm run build
• This ensures the full build pipeline runs, including Tailwind CSS compilation
• Verify the publish directory remains set to public
• Confirm Hugo version in build environment is compatible with the updated dependencies

🤖 Prompt for AI agents

Update build scripts and deployment configuration to use Tailwind v4's CLI and
ensure proper CSS compilation during deployment. The goal is to modernize the
build commands and fix the Netlify deployment pipeline.

**Update npm build scripts in package.json:**
- Update all `tailwindcss` CLI invocations to use the v4 CLI syntax
- Remove the `--jit` flag from all CLI commands (JIT mode is always enabled in
v4)
- Verify the CLI path is correct (check if
`./node_modules/tailwindcss/lib/cli.js` still exists in the v4 package
structure, or switch to using `npx tailwindcss`)
- Ensure the input/output paths remain correct: `./assets/css/main.css` →
`./static/css/main.css`
- Test both `npm run start` (development mode) and `npm run build` (production
mode) commands to verify they execute successfully

**Update netlify.toml:**
- Change the build command from `npm run fetch-stats && hugo` to `npm run build`
- This critical fix ensures the full build pipeline runs during deployment,
including Tailwind CSS compilation (previously the Netlify build bypassed npm
entirely)
- Verify the `publish` directory setting remains set to `public`
- Confirm the Hugo version specified in the build environment is compatible with
the updated dependencies

Phase 4: Validation and Compatibility Testing

Verify the upgrade maintains visual and functional parity across the site.

Task 1: CSS Feature Compatibility Verification

Test CSS features that may behave differently in v4 to ensure no visual regressions.

• Test all 62 @apply directive instances function correctly (particularly in .content, .pagination, .highlight blocks)
• Verify CSS nesting with & selectors works without the nesting plugin (test .pagination .page-item patterns with &.disabled, &:has(), &.active)
• Confirm arbitrary value syntax works (text-[2.375rem], mt-[-6.813rem], grid-cols-[35%_1fr])
• Test arbitrary selector syntax ([&>strong]:text-red, [&>a]:text-white)
• Verify gradient classes render correctly (bg-gradient-to-br from-red-dark via-red to-red)
• Check line-clamp utilities work as expected

Task 2: Template and Build Verification

Ensure all Hugo templates render correctly with the updated CSS.

• Build the site locally with npm run build and verify no build errors
• Visually inspect key pages: homepage, blog posts, simple pages, shortcode examples
• Verify custom theme colors appear correctly (text-red, bg-charcoal, text-sand, etc.)
• Test responsive breakpoints at sm, md, lg, xl viewpoints
• Confirm Netlify preview builds successfully deploy and render correctly
• Run any existing test suites to verify no regressions

🤖 Prompt for AI agents

Verify the Tailwind v4 upgrade maintains visual and functional parity across the
Hugo site. The goal is to test CSS features that may behave differently in v4
and ensure all templates render correctly.

**CSS Feature Compatibility Verification:**
- Test all 62 `@apply` directive instances function correctly, paying particular
attention to usage in `.content`, `.pagination`, and `.highlight` blocks
- Verify CSS nesting with `&` selectors works correctly without the separate
nesting plugin (test patterns like `.pagination .page-item` with `&.disabled`,
`&:has()`, `&.active`)
- Confirm arbitrary value syntax works as expected: `text-[2.375rem]`,
`mt-[-6.813rem]`, `grid-cols-[35%_1fr]`
- Test arbitrary selector syntax: `[&>strong]:text-red`, `[&>a]:text-white`
- Verify gradient classes render correctly: `bg-gradient-to-br from-red-dark
via-red to-red`
- Check that `line-clamp` utilities work as expected

**Template and Build Verification:**
- Build the site locally using `npm run build` and verify there are no build
errors
- Visually inspect key pages: homepage, blog posts, simple pages, and shortcode
examples
- Verify custom theme colors from the configuration appear correctly:
`text-red`, `bg-charcoal`, `text-sand`, etc.
- Test responsive breakpoints at sm, md, lg, and xl viewport sizes to ensure
responsive design remains intact
- Confirm Netlify preview builds successfully deploy and render correctly
- Run any existing test suites to verify no functional regressions

Research

This is a Hugo static site using Tailwind CSS v3.4.19 with a dual CSS processing approach: npm build scripts invoke the Tailwind CLI directly to compile assets/css/main.css → static/css/main.css, while Hugo templates also process CSS through a PostCSS pipeline (resources.Get | postCSS). The CSS file extensively uses @apply directives (62 instances), CSS nesting with & selectors, and arbitrary values. The current PostCSS config references plugins (tailwindcss/nesting, postcss-import) that either aren't installed or will be replaced in v4. Notably, the Netlify build command bypasses the npm build entirely, running only hugo directly—a critical issue that should be fixed as part of this upgrade.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Update the project's npm dependencies to Tailwind CSS v4 and configure the
PostCSS toolchain. The goal is to replace deprecated packages with v4-compatible
alternatives while ensuring the PostCSS pipeline is properly set up.

**Update package.json:**
- Set `tailwindcss` to version `^4.2.1`
- Add `@tailwindcss/postcss` as a devDependency (this replaces `tailwindcss` as
the PostCSS plugin in v4)
- Remove `autoprefixer` dependency (v4 handles vendor prefixing internally)
- Remove `postcss-import` from dependencies if present (v4 handles imports
internally)
- Verify that `postcss` and `postcss-cli` versions are compatible with Tailwind
v4 requirements
- Run `npm install` to generate updated `package-lock.json`

**Update postcss.config.js:**
- Replace the plugins array to use only `@tailwindcss/postcss` as the single
plugin
- Remove the `tailwindcss/nesting` plugin entry (CSS nesting is now native in
v4)
- Remove the `autoprefixer` plugin entry (now handled internally by v4)
- Remove the `postcss-import` plugin entry (now handled internally by v4)
- Optionally convert the file to ESM format (`postcss.config.mjs`) for
consistency with modern tooling
===============================================================================

Task: 2

Migrate the CSS entry file to Tailwind v4 syntax and update the JavaScript
configuration for compatibility. The goal is to adopt v4's import-based approach
while maintaining the existing JavaScript configuration file.

**Update assets/css/main.css:**
- Replace the three separate `@tailwind` directives (base, components,
utilities) with a single `@import "tailwindcss"` statement
- Add `@config "../../tailwind.config.js"` directive to explicitly load the
existing JavaScript configuration file
- Add `@source "../../content"` and `@source "../../layouts"` directives to
specify content scanning paths (this replaces the `content` array previously in
the JS config)
- Preserve all existing custom CSS, `@apply` directives (62 instances), and
nested selectors below the import statements

**Update tailwind.config.js:**
- Review and remove any deprecated options that v4 no longer supports:
`corePlugins`, `safelist`, `separator`
- Verify the custom `theme` configuration (colors, fonts, fontSizes) remains
valid under v4's structure
- Remove the `content` array from the configuration (content scanning is now
handled by `@source` directives in the CSS file)
- Ensure `extend` properties in the theme configuration are compatible with v4's
theme structure
- Remove any JIT-specific configurations (JIT mode is always enabled in v4)
===============================================================================

Task: 3

Update build scripts and deployment configuration to use Tailwind v4's CLI and
ensure proper CSS compilation during deployment. The goal is to modernize the
build commands and fix the Netlify deployment pipeline.

**Update npm build scripts in package.json:**
- Update all `tailwindcss` CLI invocations to use the v4 CLI syntax
- Remove the `--jit` flag from all CLI commands (JIT mode is always enabled in
v4)
- Verify the CLI path is correct (check if
`./node_modules/tailwindcss/lib/cli.js` still exists in the v4 package
structure, or switch to using `npx tailwindcss`)
- Ensure the input/output paths remain correct: `./assets/css/main.css` →
`./static/css/main.css`
- Test both `npm run start` (development mode) and `npm run build` (production
mode) commands to verify they execute successfully

**Update netlify.toml:**
- Change the build command from `npm run fetch-stats && hugo` to `npm run build`
- This critical fix ensures the full build pipeline runs during deployment,
including Tailwind CSS compilation (previously the Netlify build bypassed npm
entirely)
- Verify the `publish` directory setting remains set to `public`
- Confirm the Hugo version specified in the build environment is compatible with
the updated dependencies
===============================================================================

Task: 4

Verify the Tailwind v4 upgrade maintains visual and functional parity across the
Hugo site. The goal is to test CSS features that may behave differently in v4
and ensure all templates render correctly.

**CSS Feature Compatibility Verification:**
- Test all 62 `@apply` directive instances function correctly, paying particular
attention to usage in `.content`, `.pagination`, and `.highlight` blocks
- Verify CSS nesting with `&` selectors works correctly without the separate
nesting plugin (test patterns like `.pagination .page-item` with `&.disabled`,
`&:has()`, `&.active`)
- Confirm arbitrary value syntax works as expected: `text-[2.375rem]`,
`mt-[-6.813rem]`, `grid-cols-[35%_1fr]`
- Test arbitrary selector syntax: `[&>strong]:text-red`, `[&>a]:text-white`
- Verify gradient classes render correctly: `bg-gradient-to-br from-red-dark
via-red to-red`
- Check that `line-clamp` utilities work as expected

**Template and Build Verification:**
- Build the site locally using `npm run build` and verify there are no build
errors
- Visually inspect key pages: homepage, blog posts, simple pages, and shortcode
examples
- Verify custom theme colors from the configuration appear correctly:
`text-red`, `bg-charcoal`, `text-sand`, etc.
- Test responsive breakpoints at sm, md, lg, and xl viewport sizes to ensure
responsive design remains intact
- Confirm Netlify preview builds successfully deploy and render correctly
- Run any existing test suites to verify no functional regressions

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!