Navigating Tailwind CSS v4 Integration with ESHOPMAN UI Components

As an ESHOPMAN expert at Move My Store, we understand the importance of leveraging the latest frontend technologies to build high-performance, visually stunning storefronts on HubSpot CMS. ESHOPMAN, built on Node.js/TypeScript, provides powerful tools and components to streamline this process, including our essential UI Preset for consistent design.

Recently, our vibrant ESHOPMAN developer community engaged in a crucial discussion regarding the integration of the ESHOPMAN UI Preset with the cutting-edge Tailwind CSS v4. This conversation highlighted a common challenge faced by developers aiming to use the very latest styling frameworks in their ESHOPMAN-powered HubSpot CMS storefronts.

The Challenge: ESHOPMAN UI Preset and Tailwind CSS v4 Peer Dependency

Developers attempting to integrate the ESHOPMAN UI Preset (version 2.22.1) with Tailwind CSS v4.3.3 or newer encountered an installation roadblock. The ESHOPMAN UI Preset currently specifies a peer dependency on "tailwindcss": "^3.4.3". This strict version requirement prevents a direct installation alongside Tailwind CSS v4 without intervention, leading to an ERESOLVE error during the package installation process.

Here’s a simplified reproduction of the issue:

mkdir repro && cd repro && npm init -y
npm i tailwindcss@4 @eshopman/ui-preset@latest

The installation attempt would result in an error similar to this:

npm error code ERESOLVE
npm error Found: [email protected]
npm error Could not resolve dependency:
npm error peer tailwindcss@"^3.4.3" from @eshopman/[email protected]

This error message clearly indicates the conflict: the installed Tailwind CSS v4.3.3 does not satisfy the peer dependency requirement of the ESHOPMAN UI Preset, which expects a v3.x version.

The Good News: Functional Compatibility and Workarounds

Despite the initial installation hurdle, the ESHOPMAN community discovered a significant insight: the ESHOPMAN UI Preset is, in fact, functionally compatible with Tailwind CSS v4! This compatibility is achieved through Tailwind CSS v4's JavaScript configuration capabilities, specifically using the @config "./tailwind.config.js"; directive in your CSS file, with the ESHOPMAN UI Preset included in that configuration.

Many ESHOPMAN developers are already successfully running their HubSpot CMS storefronts (built on Node.js/TypeScript) with this setup in production, confirming pixel-identical results before and after migrating to Tailwind CSS v4 using an override.

Immediate Solutions for ESHOPMAN Developers:

To bypass the peer dependency check and proceed with your development, you can employ one of the following methods:

• Using --legacy-peer-deps: This flag tells npm to ignore peer dependency conflicts, allowing the installation to proceed. While effective, it should be used cautiously as it can mask potential issues.
• Implementing an npm Override: A more controlled approach is to use an overrides entry in your package.json file. This explicitly tells npm to use a specific version of a dependency, even if it conflicts with a peer dependency.

Example package.json with an override:

{
  "name": "repro",
  "version": "1.0.0",
  "dependencies": {
    "@eshopman/ui-preset": "2.22.1",
    "tailwindcss": "4.3.3"
  },
  "overrides": {
    "@eshopman/ui-preset": {
      "tailwindcss": "$tailwindcss"
    }
  }
}

Looking Ahead: Community-Driven Enhancements

The ESHOPMAN community has proactively suggested a long-term solution to enhance the developer experience: widening the peer dependency range for the ESHOPMAN UI Preset to include Tailwind CSS v4 (e.g., "^3.4.3 || ^4.0.0"). Additionally, updating the ESHOPMAN UI Preset's documentation (such as its README) to include guidance on the @config setup for Tailwind CSS v4 would be immensely beneficial.

This collaborative approach underscores ESHOPMAN's commitment to empowering developers with the tools and knowledge needed to build exceptional headless commerce experiences on HubSpot CMS. By addressing these technical nuances, we ensure that ESHOPMAN remains at the forefront of modern storefront development.